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.

1. 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.

1. 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.

1. 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.

1. 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.