ads-next

Continuous coaching: what to fix next

/ads next turns audits into a stream of small, ordered, verified actions. It's the second half of the seguimiento loop: /ads start connects, /ads audit measures, /ads next coaches.

Subcommand routing

| Arg | Behavior | |-----|----------| | (none) | Default — Discover → Rank → Top 3 → offer to walk through #1. | | show | Discover → Rank → print top 10 → exit (no walk-through prompt — good for client reports). | | compare | Print full delta between the two most-recent audits per platform via python3 scripts/profile.py compare <p>. | | walk | Skip the prompt — go straight to walking the user through the top action. |

Core rules

1. Read the profile first. python3 scripts/profile.py get — if exit 2,

suggest /ads start and exit (a coach with no context is just guessing).

1. One action at a time during walk-through. Same step-by-step verified

loop as /ads start Phase C.3.

1. Never invent issues. If no audits are found in cwd or history, print

the exact command to generate one (/ads audit or platform-specific) and exit.

Phase 1 — Discover audit JSON

Search for *-audit-results.json files in this order, newest first:

1. <cwd> — current working directory. Glob *-audit-results.json.
2. ~/.claude-ads/history/ — the persistent log. Read

~/.claude-ads/history/index.json and resolve files for the most recent audit per platform.

Validate each file:

• Must parse as JSON.
• Must include platform, health_score, checks.
• platform must be one of meta, google, tiktok.

If a file fails validation, skip it and print a single WARNING: skipped <path> (<reason>) line. Don't abort the run.

If zero valid audits found:

No audits yet. Run one first:

  /ads audit                 — full multi-platform
  /ads <meta|google|tiktok>  — single platform deep-dive

Then exit.

Phase 2 — Persist any new audits to history

For each audit file discovered in cwd that is NEWER than the most recent entry for that platform in ~/.claude-ads/history/index.json (compare generated_at), copy it to history via:

python3 scripts/profile.py save-audit <path>

This is what builds the multi-session memory — every audit run from anywhere on disk eventually ends up in the history index.

Phase 3 — Rank items by impact × ease

Pool every quick_win, every critical_issue, and every check with result in (FAIL, WARNING) across all valid audits. Deduplicate by (platform, check_id) — if a check appears in both critical_issues and checks, treat as one item using the critical metadata.

For each item, compute an impact score:

severity_weight = { critical: 5.0, high: 3.0, medium: 1.5, low: 0.5 }[severity]
effort_inverse  = 1 / (fix_time_minutes + 1)            # default fix_time = 30 if null
budget_share    = platform_budget_share(platform)       # see below
impact          = severity_weight × effort_inverse × budget_share × 100

platform_budget_share — derive from the user's profile + audit account_id presence:

• If profile lists 1 active platform, share = 1.0 for that platform.
• If profile lists 2 or 3, share = 1 / n baseline. Then bump the platform

that the user spends most on (use monthly_spend_usd ÷ platform count as the rough prior; if the user has set per-platform spend in the future, use that instead) by +0.1 (cap at 0.8).

• If profile is empty, fall back to equal weight.

Sort all items by impact descending.

Phase 4 — Regression detection (Priority 0)

For each platform with ≥2 audits in history, run:

python3 scripts/profile.py compare <platform>

Inspect the JSON output:

• score_delta < -5 → PRIORITY 0 alert appended at the top of the

ranked list. Format:

`` ⚠ <Platform> health dropped from <prev>/100 (<prev_grade>) → <new>/100 (<new_grade>) since your last audit. New issues: <comma list of new_issues> Resolved: <comma list of resolved_issues> ``

• score_delta > +5 → success line at the very bottom of the output:

🎉 <Platform> health improved <delta>+ points since last audit. Keep going.

Regressions take precedence over normal Quick Wins. They appear ABOVE the Top 3 list, with their own header.

Phase 5 — Output the top 3

Default subcommand prints:

Next actions (ranked by impact × ease for your $XXX/mo across <platforms>):

  1. [<platform> · <check_id> · <severity>] <name>
     Finding:        <finding>
     Recommendation: <recommendation>
     Estimated fix:  <fix_time_minutes> min · Impact: <impact rounded>
     Reference:      <reference file if known, e.g. tracking-meta.md>

  2. [...]

  3. [...]

(Run `/ads next show` to see the top 10. `/ads next compare` for full audit delta.)

If show subcommand: print top 10 instead, no prompt, exit.

Phase 6 — Walk-through (default and walk subcommands)

AskUserQuestion:

"Want me to walk you through fixing #1 right now?"

Options: Yes — step by step · Show me #2 instead · Exit, I'll handle it.

On Yes:

1. Determine the reference file for this check_id based on its platform

and category. Lookup table:

| Platform | Category prefix | Reference file | |----------|----------------|----------------| | meta | Tracking / Pixel / CAPI | tracking-meta.md | | meta | Creative / fatigue | meta-audit.md (Creative section — covers M28 fatigue) | | meta | Structure / Budget | meta-audit.md | | google | Tracking / Conversion | tracking-google.md | | google | Bidding / Structure | google-audit.md | | google | Quality Score / Keywords | google-audit.md | | tiktok | Tracking / Events API | tracking-tiktok.md | | tiktok | Creative / Spark | tiktok-audit.md | | tiktok | Structure | tiktok-audit.md |

If no reference matches, use the check's own recommendation field as the only source.

1. Step-by-step loop (same pattern as /ads start Phase C.3):

• Print step 1: Goal · Do this · Expect to see · How I'll verify.
• AskUserQuestion: Done — verify now · Hit an error · Pause.
• On Done: run the verification (re-call the relevant MCP tool / API

script) and confirm the check now passes. If it does → ✓, move to step 2. If not → diagnose, retry.

• Cap at 3 attempts per step.

1. After the action, ask if the user wants to proceed to action #2.

On Show me #2 instead: re-enter Phase 6 with index 2.

On Exit: print:

*Run /ads audit after you've fixed this to update your score, then `/ads

next` again for the new top 3.*

Phase 7 — Save state

At the end:

python3 scripts/profile.py set last_command "/ads next"
python3 scripts/profile.py set last_command_at "$(date -u +%FT%TZ)"

The history index updates itself when /ads audit runs next — /ads next itself doesn't add to history (it only reads + acts).

Compare mode (/ads next compare)

For each platform with ≥2 history entries:

python3 scripts/profile.py compare <platform>

Print the full diff for each: score delta, grade change, new issues, resolved issues, file timestamps. No ranking, no walk-through prompt — this is the audit changelog view.

Error handling

• Profile missing → print one-liner suggesting /ads start, exit.
• No audits anywhere → print one-liner suggesting /ads audit, exit.
• All audits failed validation → print the warnings collected and exit.
• During walk-through: if 3 retries fail, log to console "Skipped

<check_id> — come back to this with /ads next walk later" and ask whether to try #2.

Output contract

/ads next produces NO files. It is purely interactive coaching plus side-effects on ~/.claude-ads/history/ (via save-audit) and the profile's last_command* fields.