ahgraber/spec-kit-checklist

Spec Kit Checklist

Generate domain-specific checklists that evaluate requirement quality in Spec Kit artifacts.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-checklist.

When to Use

• spec.md exists and you need a checklist to review requirement quality before implementation.
• You want a focused lens (for example UX, API, security, performance, accessibility) over requirement quality.
• You need to surface ambiguity, missing coverage, or weak acceptance criteria in writing.

When Not to Use

• You are writing runtime tests, QA scripts, or implementation verification steps.
• spec.md does not exist yet (spec-kit-specify first).
• High-impact ambiguity must be resolved in-spec before checklist generation (spec-kit-clarify).
• You are generating executable tasks (spec-kit-tasks) or implementing tasks (spec-kit-implement).

Router Fit

• Primary route from spec-kit when the intent is requirement-quality checklist generation.
• Can be run as a standalone quality pass after spec-kit-specify/spec-kit-clarify and before or during implementation.
• Output checklists feed the optional checklist gate in spec-kit-implement.

Preconditions

• Run from repository root (or a subdirectory inside it).
• Active feature context resolves to one specs/<feature>/ directory.
• spec.md exists for that feature.

Workflow

1. Resolve feature paths and enforce the checklist prerequisite gate:

   • Run scripts/check-prerequisites.sh --paths-only --json exactly once.
   • Parse and retain REPO_ROOT, FEATURE_DIR, and FEATURE_SPEC.
   • If FEATURE_SPEC (spec.md) is missing, stop and route to spec-kit-specify.

2. Load checklist context:

   • Required: spec.md.
   • Optional when present: plan.md, tasks.md.
   • Extract only requirement-relevant content: requirements, acceptance criteria, edge/error cases, non-functional constraints, assumptions/dependencies.

3. Clarify checklist scope only when needed:

   • Ask up to 3 concise, high-impact questions if scope/risk/audience is unclear.
   • Skip questions already answered in user input or artifacts.
   • If ambiguity still blocks item quality, ask up to 2 targeted follow-ups (max 5 total).

4. Choose checklist file target:

   • Ensure FEATURE_DIR/checklists/ exists.
   • Derive a short domain slug from intent (for example ux, api, security, performance).
   • Create a new file per run: prefer <slug>.md; if it exists, create <slug>-2.md, <slug>-3.md, etc.
   • Never overwrite existing checklist files.

5. Generate requirement-quality checklist items:

   • Treat each item as a "unit test for requirement writing," not implementation behavior.
   • Group items under quality categories as needed:
     • Requirement Completeness
     • Requirement Clarity
     • Requirement Consistency
     • Acceptance Criteria Quality / Measurability
     • Scenario and Edge-Case Coverage
     • Non-Functional Requirements
     • Dependencies and Assumptions
     • Ambiguities and Conflicts
   • Use CHK### IDs starting at CHK001 and increment sequentially.
   • Keep items in question form and focused on what is documented or missing.

6. Apply strict item-quality rules:

   • Prefer patterns such as:
     • Are <requirements> defined/specified for <scenario>?
     • Is <term> quantified with measurable criteria?
     • Are requirements consistent between <section A> and <section B>?
   • Do not generate implementation checks (for example click/render/load/execute behavior checks).
   • Do not use runtime-verification framing (Verify, Test, Confirm) for system behavior.
   • Include traceability on most items (target: >=80%) using markers like [Spec §...], [Gap], [Ambiguity], [Conflict], [Assumption].

7. Write output using template structure:

   • Preferred template: {REPO_ROOT}/templates/checklist-template.md.
   • Fallback template: assets/checklist-template.md.
   • Preserve heading order and emit checklist rows in this format:
     • - [ ] CHK### <question> [markers]

8. Validate before final report:

   • No implementation/runtime verification items.
   • IDs are unique and sequential.
   • Items are requirement-quality questions.
   • Traceability markers meet target coverage.

9. Report completion:

   • Absolute checklist path.
   • Item count.
   • Selected focus areas, depth/audience assumptions, and any explicit must-have user constraints incorporated.
   • Reminder that each run creates a new checklist file.

Output

• New checklist file in specs/<feature>/checklists/.
• Requirement-quality checklist items with sequential CHK### IDs.
• Summary of scope assumptions and checklist focus.

Key Rules

• Evaluate the quality of requirements writing, not whether implementation works.
• Keep items objective, reviewable, and traceable to artifacts.
• Prefer concise, high-signal checklists over exhaustive low-value lists.

Common Mistakes

• Writing QA/runtime checks ("verify the API returns 200") instead of requirement-quality checks ("requirement specifies expected response codes").
• Producing vague items with no traceability marker.
• Overfitting to implementation details that do not belong in requirements artifacts.
• Overwriting an existing checklist instead of creating a new file for the run.

References

• scripts/check-prerequisites.sh
• assets/checklist-template.md
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/checklist.md