rshankras/store-signals

Store Signals

Pull what the shipped app is actually telling you and convert it into the next backlog — then verify whether last cycle's bets paid off.

This is the missing arc that turns build → ship into a loop: ship → MEASURE → DIAGNOSE → next PLAN → build → ship → measure again… The ledger (SIGNALS.md) is what makes it a loop and not a monthly report.

Where it fits (read the seams)

• Not analytics-interpretation. That interprets a metric you hand it (is 14% D7 good?). This is the end-to-end operate loop: gather every signal → cluster → diagnose → write a metric-tagged backlog → close last cycle's hypotheses. It uses analytics-interpretation's benchmarks.
• Read-only on ASC. Never responds to reviews, never mutates metadata/pricing. It surfaces, gates on explicit OK, and routes the change to the right command (next-version, bugfix, metadata).
• Feeds planning. Output is a dated backlog appended to ROADMAP.md + rows in SIGNALS.md, consumed by /apple:next-version / /apple:release.

Prerequisites

• A live (or TestFlight) app; resolve its appId from .planning/STATE.md, else list_apps + confirm.
• .planning/ context: STATE.md, APP.md, POSITIONING.md (job-to-be-done + guardrails).
• .planning/SIGNALS.md if present — the OPEN hypotheses from prior runs (each with a target metric, recorded baseline, and "check-after" date). See signals-ledger.md for the ledger + backlog formats.

Flow

1. Load prior hypotheses. Read SIGNALS.md → the OPEN rows to verify in step 5.
2. Pull the signals (read-only), this period vs trailing:
   • Reviews / ratings — list_reviews (recent, lowest-star first; flag unanswered), get_review for detail.
   • Analytics — get_analytics_report: retention, funnel/conversion, acquisition, impression→download. No report configured yet → setup_analytics_reports and note "retention/funnel lands next cycle."
   • Sales — get_sales_report: proceeds/units vs trailing 7/30-day.
   • Stability / perf — get_diagnostics (crash/hang signatures) + get_perf_metrics (launch, memory, energy).
   • Beta — list_beta_feedback_crashes if in TestFlight.
   • Listing — get_metadata to spot ASO conversion problems against current copy.
3. Normalize & cluster. Dedupe reviews into recurring themes (requests / complaints / praise) with frequency; attach magnitude (users / revenue / retention implicated). Weight by frequency × revenue impact, not by how loud one reviewer is.
4. Diagnose, filter, prioritize. Map each cluster to the core metric it moves (rating · D7 · Pro conversion · crash-free rate · ASO conversion · proceeds); score impact × confidence ÷ effort. Strategy filter: cross-check POSITIONING.md — on-strategy → backlog; off-strategy → list under "Declined (why)" (never silently drop, never silently build). Carry the app's guardrails forward. Small-N (new app): say so, lean on qualitative reviews, flag low confidence.
5. Close the prior loop. For each OPEN hypothesis whose change shipped and whose "check-after" date passed: compare the target metric now vs its baseline → WIN / REGRESSION / NEUTRAL. WIN → resolve; REGRESSION → open a revert/rethink task; NEUTRAL → keep watching or retire.
6. Write the backlog. Append a dated, metric-tagged section to ROADMAP.md and update SIGNALS.md (one row per hypothesis; formats in signals-ledger.md). Then output a ranked digest (top 3-5 "what's hurting most, why, the proposed move"), the loop-closure results, and a suggested next command (/apple:next-version, /apple:bugfix for a hot crash, /apple:metadata for an ASO fix).

Portfolio mode

With no single app (or --portfolio): run steps 2-4 across every app in list_apps, then rank which app to invest in next — biggest fixable revenue/retention/rating gap first (pairs with portfolio-health-monitor). Output one line per app + the single highest-ROI move overall.

Done

• A ranked cited digest, the WIN/REGRESSION/NEUTRAL loop-closure for last cycle, and a metric-tagged backlog written to ROADMAP.md + SIGNALS.md, with a routed next command.

Caveats

• Read-only on ASC — never auto-apply pricing, metadata, or review responses; surface → gate → route.
• Evidence over vibes — every backlog item cites its signal + magnitude; the loudest reviewer is not the roadmap.
• Always verify last cycle (step 5) before planning the next — that closure is the whole point.
• Apple delivers analytics on its own schedule; a freshly configured report is empty until next cycle.