Tutorial: From 200 missions to one Release Story

This is the end-to-end path from a pile of .intent files to a shippable decision. It ties together every concept in working with large changes using the customer portal example, which ships 15 real missions and the teaching fixtures each step produces.

The aggregation commands shown here are planned (owned by the SkillsTech Compiler). You can follow the whole tutorial today by reading the fixtures under examples/mvp-customer-portal/, which show exactly what each command will emit. The single-mission commands (intent check, build) are real now.

The setup

You (or an agent) have produced many .intent files. In the example, that is 15 missions across four feature areas: Identity and Access, Onboarding, Billing, and Deployment Readiness. Reading them one by one does not scale. Here is the path that does.

1. Validate every mission (real)

node scripts/intent-check.mjs examples/mvp-customer-portal

This runs intent check on all 15 missions. It answers "does each file parse and satisfy its own rules?" It does not answer the bigger questions. That is the rest of this tutorial.

2. Index the missions (real)

node compiler/src/cli.mjs index ./intent --json    # shipped -> mission-index.json

The Mission Atlas inventory: every mission with its feature area, a risk heuristic, guarantee and never counts, and declared verification. This command is real today; mission-index.json in the example is its actual output. Test pass counts, drift, and human review come from later steps and repo evidence.

3. View the Atlas

intent graph ./intent --view atlas   # planned

The same inventory as a tree from product down to code evidence. See Mission Atlas.

4. See the chains

intent chains ./intent           # planned -> mission-chain-map.json

The Mission Chains: Signup, Subscription Billing, and Operate and Recover. This is where you learn the billing journey is blocked even though every billing mission passes intent check.

5. Digest the session

intent summarize ./intent --since today   # planned -> intent-session-summary.json

The Build Session Digest: what the AI generated and modified, plus the Risk Radar ordering of what to review first.

6. Read the Proof Matrix

intent proof matrix ./intent     # planned -> mission-proof-matrix.json

The Proof Matrix: 9 verified, 6 partial, 1 drifting. Scan the high-risk partial/drift rows first.

7. Check the Risk Radar

Part of the summary from step 5. The top three are the under-verified billing and rollback missions. Review those, not all 15 equally. See Risk Radar.

8. Run the Semantic Diff

intent diff ./intent --since HEAD~1   # planned

The Semantic Diff: guarantees added, never rules weakened, proof gone stale. The trust-relevant changes, not the line churn.

9. Classify readiness

intent release ./intent --mvp    # planned -> mvp-readiness-report.json

The MVP Readiness report: the portal is demo_safe, bounded by Billing, with the exact blockers to reach internal_only.

10. Produce the Release Story

The trust-aware narrative of what ships and what does not: examples/mvp-customer-portal/release-story.md. It states plainly what is verified, what is authored but unproven, and what cannot yet ship.

The takeaway

• Do not make people read 200 missions.
• Make the system answer what exists, what changed, what is risky, what is verified, and what blocks deployment.
• The Atlas shows what exists; the Digest shows what changed; the Proof Matrix shows what is trusted; the Risk Radar shows what to review first; and MVP Readiness shows whether it can ship.