Self-Improving Specs

Specs are living documents. As your project evolves — new features implemented, constitution updated, lessons learned — the refinement system detects gaps and suggests improvements.

How It Works

The Refinement Command

Command: /speckit.refine

Reviews specs and presents auto-generated improvement suggestions.

/speckit.refine

What It Detects

Gap Detection

Compares spec complexity against implementation complexity. Flags specs that are thin relative to what was actually built.

Example: Spec says "handle errors" but the implementation has 15 distinct error paths. The refinement engine suggests expanding the error handling section with the actual paths.

Staleness Detection

Flags specs whose linked code has changed significantly since the last spec update.

Example: The data model spec describes 5 tables, but the implementation now has 8. The engine flags the 3 new tables as missing from the spec.

Consistency Propagation

When the constitution is updated, checks all existing specs for potential violations of the new or changed principles.

Example: A new constitution principle requires all API endpoints to have rate limiting. The engine scans specs for API definitions that don't mention rate limits.

Interactive Review

The refine command presents suggestions grouped by spec. For each suggestion, you can:

• Accept — Apply the improvement to the spec
• Reject — Skip this suggestion
• Modify — Edit the suggestion before applying

Suggestions are never applied automatically.

Quality Scoring

Each spec is scored on a 100-point rubric:

Category	Max Points	What It Measures
Completeness	30	All template sections filled, requirements have scenarios, no TODO placeholders
Consistency	25	Aligns with constitution, no conflicting artifacts, consistent terminology
Testability	25	All requirements have GIVEN/WHEN/THEN scenarios, measurable acceptance criteria
Clarity	20	No vague adjectives without metrics, no ambiguous terms, clear language
Total	100

Ratings: Excellent (90+) | Good (80+) | Fair (70+) | Poor (<70)

Spec Maturity Tracking

Every spec has a maturity level that evolves over time:

Level	Meaning	How to Reach
draft	Initial creation	Run /speckit.specify
refined	Gaps filled, clarified	Run /speckit.clarify + /speckit.refine
validated	Quality score 80+	Run /speckit.analyze with passing score
implemented	Code generated and tested	Run /speckit.implement
evolved	Updated from implementation learnings	Run /speckit.refine after implementation

Tracked in spec frontmatter:

<!-- maturity: refined -->
<!-- last_refined: 2026-02-24 -->
<!-- refinement_count: 3 -->
<!-- knowledge_coverage: 78% -->

knowledge_coverage tracks what percentage of spec sections are backed by implementation artifacts.

Constitution Learning Loop

The constitution also evolves. After implementation cycles, the /speckit.constitution command can:

1. Analyze patterns — Scan the last 3 implemented features for recurring decisions
2. Detect overrides — Find patterns where constitution principles were frequently worked around
3. Suggest new principles — Based on patterns that should be codified
4. Propagate changes — Flag specs that may violate updated principles

Example Learning Flow

1. Team implements 3 features
2. All 3 implementations add retry logic to API calls
3. Constitution command detects pattern
4. Suggests new principle: "All external API calls MUST implement retry with exponential backoff"
5. User approves → constitution updated
6. Refinement engine flags existing specs missing retry requirements

Refinement Suggestions File

Auto-generated suggestions are stored in .specify/memory/refinement-suggestions.md. This file is read by /speckit.refine and cleared as suggestions are processed.

Format:

## Suggestions for 001-user-auth

### S1: Expand error handling section
- **Type:** Gap
- **Severity:** Medium
- **Current:** "Handle authentication errors"
- **Suggested:** Add specific error paths: expired token, invalid credentials, account locked, rate limited, MFA required
- **Reason:** Implementation has 6 error paths, spec only mentions 1

### S2: Add rate limiting requirement
- **Type:** Constitution alignment
- **Severity:** High
- **Principle:** Article X — API Rate Limiting
- **Suggested:** Add non-functional requirement for rate limiting on login endpoint

Integration with Other Commands

Command	Relationship
/speckit.analyze	Pre-implementation quality check — identifies issues before building
/speckit.refine	Post-implementation improvement — learns from what was actually built
/speckit.constitution	Principle evolution — detects patterns and suggests new rules
/speckit.levelup	Team learning — captures conventions that feed back into refinements