Checklists

requirements.md

Specification Quality Checklist: Post-Merge Reliability And Release Hardening

Purpose: Validate specification completeness and quality before proceeding to planning Created: 2026-04-07 Feature: spec.md

Content Quality

  • ✅ No implementation details (languages, frameworks, APIs)
  • ✅ Focused on user value and business needs
  • ✅ Written for non-technical stakeholders
  • ✅ All mandatory sections completed

Requirement Completeness

  • ✅ No [NEEDS CLARIFICATION] markers remain
  • ✅ Requirements are testable and unambiguous
  • ✅ Requirement types are separated (Functional / Non-Functional / Constraints)
  • ✅ IDs are unique across FR-###, NFR-###, and C-### entries
  • ✅ All requirement rows include a non-empty Status value
  • ✅ Non-functional requirements include measurable thresholds
  • ✅ Success criteria are measurable
  • ✅ Success criteria are technology-agnostic (no implementation details)
  • ✅ All acceptance scenarios are defined
  • ✅ Edge cases are identified
  • ✅ Scope is clearly bounded
  • ✅ Dependencies and assumptions identified

Feature Readiness

  • ✅ All functional requirements have clear acceptance criteria
  • ✅ User scenarios cover primary flows
  • ✅ Feature meets measurable outcomes defined in Success Criteria
  • ✅ No implementation details leak into specification

Validation Notes

Self-review iteration 1 (2026-04-07)

Content Quality: The spec touches a few necessarily concrete artifacts (.kittify/config.yaml, ci-quality.yml, --strategy, mypy --strict) because the user input was a code-grounded mission that names these surfaces as the failure points to be fixed. Per the charter, these are not implementation choices being newly invented in the spec — they are constraints inherited from the validated current-main observations the user provided.

Requirement Completeness: All FR/NFR/C IDs are unique (FR-001..FR-022 with FR-023; NFR-001..NFR-006; C-001..C-006). Every row has an explicit Status. NFRs each carry a measurable threshold. No [NEEDS CLARIFICATION] markers remain — the linear-history default was resolved interactively before mission creation and locked into FR-005..FR-009 and C-001/C-002.

Feature Readiness: Every primary scenario maps to at least one FR. The Definition of Done is mechanically checkable via the Mission Close Ledger requirement.

Self-review iteration 2 (2026-04-07, post-review)

The user's structured review surfaced several gaps. All have been incorporated:

Critical:

  • ✅ FR-019 (events-commit fix) and FR-020 (regression test with git reset --hard HEAD step) added under WP05.
  • ✅ FR-021 added: WP05 must address the #415 known gap (scan_recovery_state + --base main) by either fixing it or filing a narrowing follow-up.
  • ✅ Mission 067 Failure-Mode Evidence sections added for both #415 and #416 with concrete file:line references and verification trail.
  • ✅ "Scope" subsection added to the #416 evidence pre-empting the "what about MergeState?" reviewer question.
  • ✅ WP05's "expected close with evidence" framing replaced in Assumptions with explicit pre-identified gaps.

Medium:

  • ✅ FR-009 token list locked: case-insensitive merge commits, linear history, fast-forward only, GH006, non-fast-forward. Fail-open on unknown. Backstop role made explicit.
  • ✅ FR-022 added: WP01 NFR-002 fallback narrowing if heuristic exceeds FP threshold on benchmark.
  • ✅ FR-023 added: WP04 must document #457 close-comment scope-cut (automated vs still-manual).
  • ✅ NFR-006 pinned to commit 7307389a to resolve circularity with WP03's policy work.
  • ✅ Mission Close Ledger file path named: mission-close-ledger.md in C-005 and the entity definition.

Low:

  • ✅ Scenario 2 negative-path acceptance added (override + rejected push remediation).
  • ✅ FSEvents debounce question explicitly carved out as a follow-up in Assumptions and Out-of-Scope.
  • ✅ Success Criterion 7 replaced with mechanically-checkable ledger wording.
  • ✅ DoD-4 replaced with mechanically-checkable ledger wording.

Nits:

  • ✅ FR-002 worked example added (the error_message == "foo" case).
  • ✅ NFR-001 reference numbers fixed (~9000 tests per 067 PR description, threshold relaxed to 30s).
  • ✅ #410 umbrella out-of-scope note added.
  • ✅ Dirty-classifier git check-ignore follow-up filed in Out-of-Scope.

Self-review iteration 3 (2026-04-07, post second review)

The user's second structured review surfaced one structural fix and several tightening items. All incorporated:

Structural (must-fix):

  • ✅ FR-019 and FR-020 ownership moved from WP05 → WP02. Both edits live in _run_lane_based_merge, the same function WP02 already owns for FR-005/FR-006/FR-007 strategy wiring. Lane planner will no longer need to serialize WP02 and WP05 or split them across lanes.
  • ✅ Tracked Issues table now shows #416 as "WP02 (fix) + WP05 (verification)" with an explicit footnote.
  • ✅ FR-016 cross-reference updated: "(#416, addressed by WP02 via FR-019/FR-020)" so WP05's verification report still acknowledges where the fix landed.
  • ✅ Assumptions section gap (b) updated to reflect WP02 ownership.
  • ✅ Both Mission 067 Failure-Mode Evidence sections renamed to "(A): #416 status-events loss" and "(B): #415 post-merge recovery deadlock" so a scrolling reader can't miss the second one. The (A) section body now says "WP02 owns the fix, WP05 owns the verification."

Tightening:

  • ✅ FR-019 line numbers dropped — they would have gone stale during this very mission once FR-005's strategy wiring shifted the surrounding code. Replaced with structural language ("after the per-WP _mark_wp_merged_done loop and before the worktree-removal step").
  • ✅ FR-019 sequencing note dropped — no longer needed once WP02 owns both edits.
  • ✅ FR-019 "pattern" wording fixed: safe_commit is described as the helper imported from specify_cli.git, not a "pattern."
  • ✅ FR-020 logical hole fixed. The previous version's git reset --hard HEAD step was a no-op for the events file (the merge already committed it; HEAD already contains it; the reset would not distinguish "events committed" from "events never written"). Replaced with the simpler direct assertion: git show HEAD:kitty-specs/<mission>/status.events.jsonl contains a to_lane: done entry for every WP.
  • ✅ FR-002 absorbs the "no test-suite load" behavior constraint that was incorrectly placed in NFR-001. NFR-001 is now purely wall-clock.
  • ✅ Scenario 7 added: "Maintainer starts a downstream WP after upstream lanes have merged." Gives FR-021 a user-facing motivation that's discoverable from the scenarios section instead of buried in the failure-mode evidence prose.

Style nits:

  • ✅ Out-of-scope item 7 (dirty classifier) reworded — "workaround exists" framing instead of dismissing impact in automation contexts.

Cross-FR sequencing

  • All _run_lane_based_merge edits are now WP02-owned. No cross-WP serialization required for the merge command surface.
  • WP05 is now cleanly scoped to: (1) recovery.py/implement.py edits for FR-021, (2) verification report covering both pre-identified gaps and any newly-discovered shapes, (3) Mission Close Ledger authorship.

Result

All checklist items pass on iteration 3. Spec is ready for /spec-kitty.plan.