# Speckit.freeze

> Formally close and lock a Build Step after successful implementation, validation, and review. The irreversible acceptance gate that marks a build-step as complete, reviewed, merge-ready, and safe to build upon.

- Skill: `majiayu000/speckit-freeze` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/speckit-freeze`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/speckit-freeze/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/speckit-freeze

---


# /speckit.freeze — Build Step Closure Primitive

## Purpose

**Formally close and lock a Build Step** after successful implementation, validation, and review.

`/speckit.freeze` is the **irreversible acceptance gate** that marks a build-step as:
- Complete
- Reviewed
- Merge-ready
- Safe to build upon

It prevents spec drift, retroactive edits, and silent regressions.

---

## When to Use

Activate this skill when:
- `/speckit.constitution` → satisfied
- `/speckit.specify` → finalized
- `/speckit.plan` → implemented
- `/speckit.tasks` → completed
- `/speckit.analyze` → 0 CRITICAL / 0 HIGH issues
- Implementation exists and tests pass
- A PR is ready (or merged)
- User explicitly requests to freeze a build step or tag

**Trigger phrases:**
- "freeze this build step"
- "lock in this implementation"
- "create a freeze record for [tag]"
- "close out this phase"
- "/speckit.freeze [tag-name]"

---

## Command Signature

```
/speckit.freeze [tag-name]
```

Optional parameters:
- `tag-name`: Git tag to associate with the freeze (e.g., `v0.2.0-phase8-migration`)
- `build_step`: Build step number (auto-detected from spec if not provided)
- `branch`: Branch name (auto-detected if not provided)

---

## Validation Preconditions

Before accepting a freeze, I MUST verify:

### ✅ Requirements Coverage
- All Functional Requirements mapped to implemented tasks
- All Success Criteria either:
  - Fully validated, OR
  - Explicitly deferred and documented

### ✅ Test Coverage
- Test coverage meets constitutional threshold (typically ≥80%)
- All critical paths have test coverage
- Tests pass (no failing tests blocking merge)

### ✅ Analysis Findings
- 0 CRITICAL issues unresolved
- 0 HIGH severity issues unresolved
- All MEDIUM/LOW issues either:
  - Resolved, OR
  - Explicitly acknowledged and deferred

### ✅ Constitution Compliance
- No constitution violations
- All deferrals explicitly acknowledged
- No silent assumptions or TODOs remaining

### ✅ Implementation Artifacts
- Code exists and is committed
- Documentation is updated
- No placeholder or stub code

**If ANY condition fails → FREEZE REJECTED**

---

## Freeze Record Format

When `/speckit.freeze` is ACCEPTED, output this canonical format:

```
/speckit.freeze — ACCEPTED ✅

Build-Step: [N] — [Name]
Status: FROZEN
Date: [YYYY-MM-DD]
Branch: [branch-name]
Tag: [tag-name]
Commit: [commit-hash]

Validation Summary:
- Requirements Coverage: [X]% ([Y]/[Z])
- Test Coverage: [X]%
- Tests: [passed] passed, [skipped] skipped, [failed] failed
- Analysis: 0 CRITICAL / 0 HIGH issues
- Constitution: Compliant (explicit deferrals noted)

Deferred (Explicit):
- [Item 1] → [Future Build-Step/Phase]
- [Item 2] → [Justification]

Files Modified:
- [List of key files changed]

Immutability Rule:
This build-step is now FROZEN.
❌ No spec changes allowed
❌ No task edits allowed
❌ No behavior changes allowed

Changes require: New build-step OR explicit corrective PR.

Next Actions:
1. [Merge or create PR if not already done]
2. [Tag confirmed: tag-name]
3. [Begin next build-step or phase]

Congratulations — you have a stable architectural baseline.
```

---

## Failure Mode

If validation fails, output:

```
/speckit.freeze — REJECTED ❌

Build-Step: [N] — [Name]

Reason:
- [Specific failure reason 1]
- [Specific failure reason 2]

Required Actions:
- [Action 1]
- [Action 2]

Please address these issues and retry /speckit.freeze.
```

**No ambiguity. No soft language.**

---

## Immutability Rules

After `/speckit.freeze` ACCEPTED:

### ❌ NOT Allowed Without New Build-Step:
- Spec changes (FR, NFR modifications)
- Task list modifications
- Behavior changes to frozen features
- API contract modifications

### ✅ Allowed:
- Bug fixes (via corrective PR with analysis)
- Documentation updates
- Performance improvements (non-behavior-changing)
- New features (require new build-step)

### Exception Process:
For any changes to frozen code:
1. Create issue documenting need
2. Run `/speckit.analyze` on proposed changes
3. Create corrective PR with freeze impact analysis
4. Merge with explicit "breaks freeze [tag]" notation

---

## Workflow Integration

```
Constitution → Specify → Clarify → Plan → Tasks → Implement → Analyze → FREEZE
     ↓           ↓          ↓        ↓       ↓        ↓         ↓         ↓
  [Autopilot watches at every phase, but FREEZE is manual gate]
```

`/speckit.freeze` is typically invoked:
- After PR approval but before merge
- As part of PR description generation
- When creating a release tag
- After completing all tasks in a build step

---

## Examples

### Example 1: Successful Freeze After Phase 8

```
User: /speckit.freeze v0.2.0-phase8-migration

/speckit.freeze — ACCEPTED ✅

Build-Step: Phase 8 — Migration from External Supabase
Status: FROZEN
Date: 2026-01-01
Branch: 002-local-supabase-docker
Tag: v0.2.0-phase8-migration
Commit: cfc8d18

Validation Summary:
- Requirements Coverage: 100% (8/8 tasks completed)
- Test Coverage: 85% (vector embedding preservation verified)
- Tests: All export/import scripts validated
- Analysis: 0 CRITICAL / 0 HIGH issues
- Constitution: Compliant

Deferred (Explicit):
- None for this phase

Files Modified:
- scripts/export_from_external.sh (export script)
- scripts/import_to_local.sh (import script)
- docs/supabase_migration.md (migration guide)
- specs/002-local-supabase-docker/tasks.md (all T074-T081 complete)

Immutability Rule:
Phase 8 is now FROZEN. Any changes to migration tooling require
a new phase or corrective PR with impact analysis.

Next Actions:
1. PR may be merged (tag already pushed)
2. Begin Phase 9: Documentation & Polish, or
3. Open new feature branch for next build-step

Congratulations — Phase 8 provides a stable migration baseline.
```

### Example 2: Rejection Due to Coverage

```
User: /speckit.freeze

/speckit.freeze — REJECTED ❌

Build-Step: 3 — User Authentication

Reason:
- Test coverage is 73% (below 80% constitutional threshold)
- 1 HIGH severity issue: FR-015 ambiguous password reset behavior
- 2 CRITICAL tests failing: auth_logout_test, auth_session_timeout

Required Actions:
- Fix failing tests
- Clarify password reset behavior in spec
- Re-run /speckit.analyze
- Retry /speckit.freeze

Please address these issues before freezing.
```

---

## Special Logic for This Project

For **gitea-ai-codereview** specifically:

### Build-Step Detection
- Build steps are tracked in `specs/` directory
- Each major feature has its own spec directory (e.g., `specs/002-local-supabase-docker/`)
- Tags follow pattern: `v{major}.{minor}.{patch}-{phase}`

### Validation Sources
- Check `specs/*/tasks.md` for completion status
- Check `tests/` directory for test coverage
- Check `specs/*/contracts/` for implementation artifacts
- Run `pytest` for test results

### Constitution Reference
- Constitution is in: `docs/Spec-Kit-Doc-Framework.md` or `.specify/memory/constitution.md`
- Test coverage threshold: 80% (adjustable per project)

---

## Why This Matters

**Without `/speckit.freeze`:**
- Build steps blur together
- Specs rot over time
- "Just one more tweak" destroys traceability
- No clear point of stability

**With `/speckit.freeze`:**
- Every step becomes a trustworthy foundation
- Reviews become meaningful artifacts
- Future work accelerates instead of compounding risk
- Clear audit trail of what was decided when

---

## Technical Implementation Notes

When invoked, `/speckit.freeze` should:

1. **Detect current context**:
   - Find active spec directory (e.g., `specs/002-local-supabase-docker/`)
   - Read `tasks.md` for completion status
   - Check git status for uncommitted changes

2. **Run validation checks**:
   - Parse tasks.md for `[x]` completion
   - Run pytest and capture coverage report
   - Check for common issues (TODO, FIXME, placeholder comments)
   - Verify all contracts/ documents exist

3. **Generate freeze record**:
   - Compile validation results
   - List all modified files
   - Note any explicit deferrals
   - Format canonical output

4. **Create/git tag if provided**:
   - Tag current commit with provided tag name
   - Push tag to remote if confirmed

5. **Signal next actions**:
   - Merge PR or create one
   - Begin next phase
   - Or await user decision

---

## Tips for Effective Use

1. **Run after implementation is COMPLETE** - Not during development
2. **Ensure tests pass locally first** - Freezing with failing tests defeats the purpose
3. **Review the freeze record** - This becomes your audit trail
4. **Tag appropriately** - Use semantic versioning with phase identifiers
5. **Document deferrals clearly** - Anything not done must have explicit rationale

---

## Integration with Other Spec-Kit Commands

```
/speckit.constitution  → Set principles
/speckit.specify       → Define requirements
/speckit.clarify        → Resolve ambiguities
/speckit.plan           → Design architecture
/speckit.tasks          → Break down work
/speckit.implement      → Execute tasks
/speckit.analyze        → Review quality
/speckit.freeze         → ✅ LOCK IT IN
```

The freeze is the final gate that closes the loop.