Checklists

requirements.md

Specification Quality Checklist: Operator Config & Install Ergonomics

Purpose: Validate specification completeness and quality before proceeding to planning Created: 2026-08-16 Updated: 2026-08-16 (post-spec squad revision) Feature: spec.md · Design record: design-record.md

Content Quality

  • ✅ No implementation details that preclude alternatives (technical anchors named as constraints)
  • ✅ Focused on operator value and correctness outcomes
  • ✅ Written to be reviewable by non-implementers (user stories lead)
  • ✅ All mandatory sections completed (+ Dependencies & Assumptions)

Requirement Completeness

  • ✅ No [NEEDS CLARIFICATION] markers remain
  • ✅ Requirements are testable and unambiguous (FR-008 allowlist/denylist contradiction resolved → fail-closed allowlist)
  • ✅ 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 (delta-vs-baseline load, 0 secrets, 0 absolute paths, byte-identical)
  • ✅ Success criteria are measurable
  • ✅ Success criteria are technology-agnostic where the outcome allows
  • ✅ All acceptance scenarios are defined (FR-003→US4.4; FR-006 fail-loud→US2/FR-006 note; FR-008→US2.6; pre-import→US2.4; unreadable→US2.5; re-bake→US1.4)
  • ✅ Edge cases are identified and each maps to a scenario or gated constraint
  • ✅ Scope is clearly bounded (rc-cadence producer half → #3047; HOME excluded; no CONFIG_HOME var)
  • ✅ Dependencies and assumptions identified (dedicated section: #3493/#3494/#3495/#3496, #3047 interface, #3381 migration ordering, #3251/#3022/#2519)

Feature Readiness

  • ✅ All functional requirements have clear acceptance criteria
  • ✅ User scenarios cover primary flows (5 prioritized stories P1–P3)
  • ✅ Feature meets measurable outcomes defined in Success Criteria
  • ✅ No implementation details leak into specification beyond named constraints

Post-spec squad resolutions (3 lenses: reviewer-renata / architect-alphonso / planner-priti)

  • FR-008 allowlist vs denylist contradiction → fail-closed allowlist (title/body/NFR-004/Key Entities aligned).
  • Pre-import shim must beat __init__.py:36 → FR-004 + US2.4 scenario.
  • Two-tier setdefault merge order (per-repo over home, then setdefault) → FR-004 + US2.3.
  • Present-but-unreadable fails loud → FR-004a + US2.5.
  • Doctor config-health + channel facet → FR-010 + US4.4 / US3.4.
  • Single shared path→token normalizer for both carriers → FR-001.
  • get_packs_root_default() = .parent arithmetic → FR-006.
  • Scaffold must not seed PACKS_ROOT (TEMPLATE_ROOT gate) → C-003a + US4.2.
  • Re-bake footgun (PACKS_ROOT=abs exported) → C-003 + US1.4 + SC-001.
  • Two independent migrations + doctor.py per-check ownership (#1623) → Dependencies & Assumptions.
  • #3047 discovery interface + #3381 migration-ordering → Dependencies & Assumptions.
  • Dangling .kittify/mission-brief.md reference → replaced by committed design-record.md.

Notes

  • The env-templated-vs-repo-relative and HOME-scope decisions were resolved with the operator (token provenance; HOME excluded; located via SPEC_KITTY_HOME; two-tier overlay).