spec-kitty / spec-kitty/spec-kitty

Make /spec-kitty.analyze a true pre-implementation readiness review

Open
#849 1 comment 0 reactions 0 assignees View on GitHub
enhancement epic priority:P2 workflow
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Problem

`/spec-kitty.analyze` currently behaves like a lightweight cross-artifact consistency check over `spec.md`, `plan.md`, `tasks.md`, and charter. That is useful, but it is too narrow for the role it occupies in the workflow: the last optional quality gate after `/spec-kitty.tasks` and before `spec-kitty next` starts agent execution.

By that point the mission has more artifacts than the command reviews: `meta.json` intent fields, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, optional planning artifacts such as `occurrence_map.yaml`, `tasks.md`, and the individual `tasks/WPxx-*.md` work-package prompts. The current prompt can miss big-picture user-intent drift, planning-artifact contradictions, bad WP decomposition, missing WP readiness metadata, and overbuilt or poorly sequenced delivery slices.

## Product owner view

This command should become a **Pre-Implementation Readiness Review**. It should answer: "Are we about to send implementation agents into a plan that actually matches the user's goal, is internally coherent, and is decomposed into executable WPs?"

## Desired outcome

`/spec-kitty.analyze` should review the full planning corpus and produce a concise readiness verdict before implementation begins.

Minimum review dimensions:

1. Intent fidelity: compare `meta.json`/source intent/purpose fields against `spec.md`, `plan.md`, `tasks.md`, and WPs.
2. Specification quality: FR/NFR/user-story/edge-case completeness and ambiguity checks.
3. Planning artifact consistency: `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, decisions, and optional mission-specific artifacts.
4. Work-package readiness: every WP prompt exists, is well-sized, has sufficient context, DoD, risks, dependencies, ownership, branch strategy, and reviewer guidance.
5. Coverage and mapping: every requirement maps to WPs; every WP maps back to user value/requirements; all planning artifacts are represented in tasks.
6. Execution readiness: use or recommend `finalize-tasks --validate-only` to catch dependency cycles, missing requirement refs, ownership overlaps, and invalid frontmatter before `spec-kitty next`.
7. Product coherence: MVP slice, sequencing, overbuild risk, missing user-value slice, and whether the plan still solves the original problem.

## Acceptance criteria

- The analyze command prompt is reframed as a pre-implementation readiness review after `/spec-kitty.tasks` and before `spec-kitty next`.
- It explicitly loads and reasons over the full mission planning corpus, not only `spec.md`, `plan.md`, and `tasks.md`.
- It reviews individual `tasks/WPxx-*.md` prompt files, not just the task index.
- It emits a readiness verdict: ready, ready-with-caveats, or blocked.
- It produces actionable findings grouped by severity and by artifact.
- It tells the user whether to proceed to `spec-kitty next` or return to specify/plan/tasks.

## Notes

This issue follows a product review of the current command template. Current docs already recommend `/spec-kitty.analyze` after `/spec-kitty.tasks`, but the command behavior is not broad enough to be trusted as the last planning gate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.