| name | A4 — North Star Direction |
| description | Vision-gap analysis. Compared to the perfect-world North Star, what is missing, drifting, or underbuilt — and what to add or change now to close the gap. Not a passive alignment scorecard. |
| argument-hint | <group-number> [feature-name] |
A4 — North Star Direction (Gap Analysis)
The vision-gap check — and emphatically not a passive alignment scorecard. A4 asks: compared to the North Star (the perfect-world vision for this feature), what is missing, drifting, or underbuilt — and what should we add, build, or change now to close that gap? For every quality dimension it asks "what would perfect look like here, and what is the delta?" and produces concrete improvements to make, not checkmarks. This lens requires top-tier judgment.
Inputs
northstar.md (required — refuse if missing) · the implementation code in scope · the micro specs · design.md- The constitution · prior A1–A3 reports · the project mode
- Accumulated
domain-learnings.md from prior A4 runs (extra, project-earned quality expectations)
Process
- Read the North Star deeply — internalize every dimension, compass question, and emotional quality; understand what "perfect" means for this feature.
- Walk each quality dimension (weighted Critical / Important / Nice). For each: what does perfect look like for this implementation? what is the current state? what is the gap? Score Aligned / Drifting / Missing. For anything drifting or missing, state the specific change that closes the gap. Critical-dimension gaps are urgent.
- Walk the compass questions — apply each to the implementation's decisions; flag any that fail, and state what passing would look like.
- Assign severity by dimension weight: Critical → High/Critical · Important → Medium · Nice → Low (still fixed).
- Make every finding actionable — never "this doesn't feel right," always a concrete change (e.g. "the settings panel shows 12 options at once; the North Star calls for cognitive-load minimization — group into 3 categories of 4").
- Capture domain learnings — record domain-specific quality observations that emerged from the work itself, appended to
domain-learnings.md, tagged with the feature/domain. They accumulate: each future A4 run reads them as additional expectations. This is how the audit gets smarter about a domain over time.
- Write the report to
audits/{scope}-a4.md: per-dimension Aligned/Drifting/Missing with gap analysis, compass-question results, actionable findings, captured observations, and an overall direction assessment.
Findings beyond this scope
A4 has a fourth disposition: defer what's blocked — with a concrete pickup path and a named blocker. Any finding suggesting a change beyond this spec's scope is written into the feature's design-inputs.md (a plain markdown journal of spec-amendment inputs). This is not a deferral-with-no-record — it converts the gap into a tracked work item. The open-finding count still reaches zero.
Shared machinery
Finding format, the zero-tolerance loop (even Nice-dimension drift is fixed), and conviction: see docs/the-audit-system.md.
Natural language triggers
- "a4 audit group 1"
- "north star gap analysis"
- "what's missing vs the vision"
