requirement-quality

# Requirement Quality

## Config Resolution

Skill supports project-specific standards. Order:

1. Look for `.lattice/config.yaml` in repo root
2. If found, check `paths.requirement_standards` for custom doc path
3. If custom path exists, read doc and check YAML frontmatter for `mode`:
   - **`mode: override`** (or no mode): Custom doc full precedence. Use instead of embedded defaults. Must be comprehensive — sole reference.
   - **`mode: overlay`**: Read embedded `./references/defaults.md` first, then apply custom doc sections on top. Custom sections replace matching sections in defaults (matched by heading). New sections appended after.
4. If no config/path/file, read `./references/defaults.md`

Defaults ship with skill. Opinionated best practice. Work out of the box. Override only when team has different standards.

Custom standards produced by `requirement-forge-refiner` → consumed by this atom → composed by `requirement-forge` molecule. Run refiner once per project. Re-run when standards evolve.

## Self-Validation Checklist

STOP before writing any feature file. Verify ALL checks. If check clearly fails → fix before writing. If judgment call (see Ambiguity Signals) → flag and surface options.

**If validating an existing spec** (not generating), same checks apply — "fix before writing" means "fix before marking approved." Present findings as a quality report with severity.

**Draft vs approved enforcement**: For `status: draft` — items 1, 2, 10 are required (core framing must be right from the start). Items 3–9, 11, 12 are advisories: flag findings but do not block write. For `status: approved` — all items required, no exceptions.

1. **PROBLEM STATEMENT**: Names a specific user need or pain — not a solution in disguise, not a vague improvement? Identifies WHO has the problem (specific user type or role, not "users")? "We need a dashboard" is a solution. "Users cannot track their order status after checkout" is a need — but which users? Buyers? Admins?
2. **SCOPE**: Has explicit out-of-scope items — not just in-scope? An incomplete scope boundary is no boundary at all.
3. **BOUNDARY CONDITIONS**: Feature-wide edge cases, system limits, and constraints documented?
4. **ASSUMPTIONS**: Statements the team proceeds with as true are explicit — not buried in ACs or unstated? If an assumption proves wrong, affected scenarios are identifiable?
5. **SCENARIO NAMES**: Each scenario has a verb-phrase name (sentence case) that describes the situation — not a feature name, not an AC?
6. **AC FORMAT**: Each AC follows the agreed format (default: Given/When/Then)? Each has a clear pass/fail condition? Pass/fail is clear when a tester can write an automated check without asking a clarifying question. Outcomes requiring interpretation ("responds", "handles", "works correctly") must be rewritten with specific, observable outcomes.
7. **FAILURE COVERAGE**: At least one scenario covers a failure, error, or edge case — not all success paths?
8. **SCENARIO COUNT**: Feature has no more than the agreed max (default: 5) scenarios? If at or over → challenge whether this is one feature or two.
9. **AC COUNT**: Each scenario has no more than the agreed max (default: 6) ACs? If at or over → challenge whether this scenario is too broad.
10. **INDEPENDENCE**: Feature is self-contained — no unresolved external unknowns required before design-blueprint can begin? Check Open Questions section — any unresolved question affecting scope, behavior, or ACs is a blocker. Feature cannot pass this check with non-empty Open Questions unless each is marked non-blocking with a stated reason.
11. **IMPLEMENTATION NOTES**: Slices ordered chronologically, at the "what" level — no technical implementation specifics?
12. **COHERENCE**: Do all scenarios address the same user need stated in the Problem Statement? If a scenario serves a different need, it belongs in a separate feature.

Project-specific checks: if loaded doc contains a validation checklist section, apply those after base checklist.

When all checks pass: output "Spec passes requirement-quality — ready for write." (pre-write mode) or "Spec passes requirement-quality — status: approved." (validation mode).

## Active Anti-Pattern Scan

After checklist, scan for these. If found → fix or challenge before writing.

- [ ] **Solution as problem**: Problem statement says "we need X" instead of "users cannot do Y" → ask what user need X addresses; rewrite around the need
- [ ] **Vague problem**: "improve the experience", "make it faster", "better UX" → no verifiable outcome; push for specific, observable user impact
- [ ] **Persona-less problem**: Problem statement says "users" without identifying which user type or role → push for specificity; different personas produce different ACs
- [ ] **Hidden assumption**: AC or scenario relies on an unstated assumption ("assumes user is logged in" but no Assumptions section records this) → make the assumption explicit or add a scenario covering the case where it doesn't hold
- [ ] **Boundaryless scope**: scope section lists only what is in scope, nothing explicitly out → force at least 3 explicit exclusions; undefined scope = infinite scope
- [ ] **Happy-path-only spec**: every scenario is a success path, no failure or error scenario → add at least one failure scenario before feature is complete
- [ ] **AC sprawl**: single scenario accumulates 7+ ACs → scenario too broad; propose split into two named scenarios
- [ ] **Scenario sprawl**: feature has 6+ scenarios → feature may be two; pause and challenge scope before adding more
- [ ] **Vague AC**: "the system should handle errors gracefully", "response should be fast", "it should work correctly" → no pass/fail condition; rewrite as concrete Given/When/Then
- [ ] **Implementation AC**: AC specifies a technical approach ("system shall use Redis", "shall call the /api/v2 endpoint") → requirements specify behavior, not implementation; rewrite as observable outcome
- [ ] **Orphaned feature