Learning Map
For the Student persona: the sequence of concepts you traverse while shipping a first real project through Throughspec. Each concept is answered in learnings.md as you go.
Deciding
What is a spec?A frozen artifact that turns interpretation into agreement. Everything downstream is traceable back to a clause.Cross-questioningWhy we do ≥3 rounds before writing code. The technique is older than software; the enforcement is new.Load-bearing categoriesUsers, jobs-to-be-done, success metric, constraints, non-goals. Skip one and the code drifts.Designing
Design tokensNamed values (colors, spacing, type) that let a system stay consistent even as components change.Reference-driven vs inferredWhen to trust a reference vs invent from constraints. And when to refuse to invent.SurfacesThe map of physical UI regions - nav, content, marginalia. Design happens per surface, not per page.Planning
Step-by-step planWhy 8-10 steps, each with a standalone-testable-runnable deliverable. Each step ships or the plan is wrong.Acceptance criteriaTurning "make it work" into a runnable test. Weak criteria demand constant clarification.Effort bandsS / M / L relative sizing. Absolute time estimates lie; relative sizing survives.Building
The 6 stepsRequirements → Architecting → Product → Tech → Planning → Writing Code. Ordered because each depends on the previous.Sub-agentsTool-scoped actors. spec-interrogator can only Read. spec-coder can Write. Least-privilege by construction.Memory-update ordercontext.md first, CHANGELOG.md last. Why the order matters when compaction runs.Maintaining
Reproduction-first bug fixingThe recipe IS the regression test. No recipe → no fix cycle.Diff-scoped refactorCleaning only what you touched. Compensating audit log makes drift observable.Compression/spec-sync folds oldest entries with a compressed-from block. Recency stays verbatim.Write it down
After every step, ask Claude "Why this step?" and append the answer to learnings.md. Six months later, that log is worth more than the code.