krankie-audit

name	krankie-audit
description	Run an ASO audit on canonical App Store metadata under `./metadata`, then a krankie-based competitor keyword-gap analysis (no Astro subscription). Krankie replacement for asc-aso-audit. Use after `asc metadata pull`.

ASO Audit (krankie)

Two-phase ASO audit. Phase 1 (offline metadata checks) is identical to asc-aso-audit and needs no network. Phase 2 replaces Astro's popularity/competitor analysis with krankie competitor rank-gap analysis.

What changes vs the Astro version: krankie gives rank position only - there is no popularity score, no difficulty score, and no keyword-suggestion engine. So Phase 2 finds gaps by competitor rank (keywords a competitor ranks well for that VivaDicta does not), not by popularity.

Preconditions

• Metadata pulled into canonical files: asc metadata pull --app "6758147238" --version "X.Y.Z" --dir "./metadata".
• For Phase 2: krankie tracking the app + competitors (the VPS at lobster@openclawtail is already set up; see krankie-rankings).

Phase 1: Offline Checks (unchanged)

Run the same offline checks as asc-aso-audit against ./metadata. Read .agents/skills/asc-aso-audit/references/aso_rules.md for the exact rules. Summary:

1. Keyword waste - tokens in subtitle/name that also appear in keywords (already indexed, wasted budget).
2. Underutilized fields - keywords < 90/100 chars, subtitle < 20/30 chars.
3. Missing fields - empty subtitle/keywords/description/whatsNew.
4. Bad separators - spaces after commas, semicolons, or pipes in keywords.
5. Cross-locale gaps - non-primary locale keywords identical to en-US (not localized).
6. Description keyword coverage - tracked keywords missing from the description (conversion, not indexing).

Metadata paths: app-info metadata/app-info/{locale}.json (subtitle); version metadata/version/{latest}/{locale}.json (keywords, description, whatsNew). Primary locale en-US.

Phase 2: krankie Competitor Rank-Gap Analysis

Pull current rankings for VivaDicta + the 3 tracked competitors from the VPS (canonical history):

ssh lobster@openclawtail 'export PATH="$HOME/.bun/bin:$PATH"; krankie rankings --json'

Apps in the krankie DB:

• VivaDicta 6758147238 (own)
• Otter 1276437113, Wispr Flow 6497229487, Whisper Transcription 1668083311 (competitors, US)

Steps

1. Build a per-keyword rank table for US: VivaDicta rank vs each competitor's rank (current_rank, null = not in top 200).
2. Surface gaps: keywords where a competitor ranks (especially top-50) and VivaDicta is unranked or much worse. These are the highest-value targets - a rival is capturing search traffic you are not.
3. Rank gaps by competitor strength: sort by best competitor rank ascending (a keyword where Otter is #3 and we are unranked outranks one where a competitor is #150).
4. Diff against metadata tokens: for each gap keyword, check whether its component tokens are present in subtitle + name + keywords of any locale. If the tokens are missing, that explains the gap and is an actionable add. If tokens are present but VivaDicta still doesn't rank, the issue is competition/authority, not coverage.
5. Cross-field combo note: remember keywords combine within a locale across title + subtitle + keywords. Flag combos enabled by adding a single token (e.g. adding recorder when voice is already indexed enables "voice recorder").

Skip conditions

• VPS unreachable - run krankie locally on the MacBook (krankie rankings --json), noting the local DB may be sparse; or skip Phase 2 with a note.
• A keyword not tracked yet - add it: krankie keyword add 6758147238 "<kw>" --store us (and for competitors to compare).

Output Format

### ASO Audit Report (krankie)

**App:** VivaDicta - Speech to Text | **Primary Locale:** en-US
**Metadata source:** metadata/version/X.Y.Z

#### Field Utilization
| Field | Value | Length | Limit | Usage |
...

#### Offline Checks
| # | Check | Severity | Field | Locale | Detail |
...
**Summary:** X errors, Y warnings across Z locales

#### Competitor Rank-Gap (krankie, US)
| Keyword | VivaDicta | Otter | Wispr Flow | Whisper Trans. | In metadata? | Action |
|---------|-----------|-------|------------|----------------|--------------|--------|
| voice typing | - | #2 | #1 | - | tokens present | competition, not coverage |
| dictation keyboard | #164 | - | #1 | - | partial | reinforce combo |

#### Recommendations
1. [Errors first]
2. [Keyword waste]
3. [Utilization]
4. [Highest gap opportunities by competitor strength]

Notes

• Phase 1 works with zero network access - the audit is useful even if the VPS/krankie is down.
• No popularity data: prioritize by competitor rank, not popularity. If you later resubscribe to Astro, asc-aso-audit Phase 2 adds popularity + suggestions back.
• After metadata changes, run krankie-rankings to measure impact (ranks settle over 1-2 weeks).
• Related: krankie-rankings (dated rankings report), asc-aso-audit (Astro-based original).