ss-tools/.opencode/command/speckit.resume.md

description

description
Reconstruct active feature and phase state after interruption. Read-only except for an optional specs/<feature>/resume.md bounded snapshot. Never mark tasks complete or rerun create-new-feature.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Principle

You are recovering state after an interruption — agent crash, context loss, session timeout, or user returning after a break. You do NOT modify user changes, mark tasks complete, or create new feature branches. Your job is to inspect what exists and report exactly where the workflow stands.

Outline

Phase 0: Read-Only Pre-Flight

1. Run prerequisites: Run .specify/scripts/bash/check-prerequisites.sh --json --paths-only from repo root. Parse FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS.
2. Check git status (do NOT modify working tree):

   git status --short
   git branch --show-current
   git log --oneline -5
   

   Report: current branch, uncommitted changes count, recent commits. If on a feature branch (NNN-short-name) that matches the detected FEATURE_DIR, confirm alignment. If branch and FEATURE_DIR mismatch, report the inconsistency (do NOT switch branches).

Phase 1: Phase Detection — Which Workflow Phase Are We In?

Inspect artifacts to determine the current phase. Use this decision tree:

Artifact Present?	Phase
No FEATURE_DIR/spec.md	Pre-Spec — run /speckit.specify
spec.md exist, no plan.md	Specification — after /speckit.specify, before /speckit.plan. Check for /speckit.clarify state.
spec.md + plan.md, no tasks.md	Planning — after /speckit.plan, before /speckit.tasks
spec.md + plan.md + tasks.md, no validation.md	Task Decomposition — after /speckit.tasks, before /speckit.validate or /speckit.implement
validation.md exists with PASS	Ready to Implement — run /speckit.implement
validation.md exists with BLOCKED	Blocked — resolve findings, re-run /speckit.validate
Tasks partially checked [x]	Mid-Implementation — some tasks done, some remaining

Phase 2: Artifact Inventory

Inspect all artifacts in FEATURE_DIR/ and list their state:

Artifact	Path	Exists?	Size	Last Content Change
spec.md	FEATURE_DIR/spec.md	✅/❌	N lines	[date]
ux_reference.md	FEATURE_DIR/ux_reference.md	✅/❌	N lines	[date]
plan.md	FEATURE_DIR/plan.md	✅/❌	N lines	[date]
research.md	FEATURE_DIR/research.md	✅/❌	N lines	[date]
data-model.md	FEATURE_DIR/data-model.md	✅/❌	N lines	[date]
traceability.md	FEATURE_DIR/traceability.md	✅/❌	N lines	[date]
quickstart.md	FEATURE_DIR/quickstart.md	✅/❌	N lines	[date]
tasks.md	FEATURE_DIR/tasks.md	✅/❌	N lines	[date]
contracts/modules.md	FEATURE_DIR/contracts/modules.md	✅/❌	N lines	[date]
contracts/ux/	FEATURE_DIR/contracts/ux/	✅/❌	N files	[date]
prototype/index.html	FEATURE_DIR/prototype/index.html	✅/❌	N bytes	[date]
contracts/openapi.yaml	FEATURE_DIR/contracts/openapi.yaml	✅/❌	N lines	[date]
validation.md	FEATURE_DIR/validation.md	✅/❌	PASS/BLOCKED	[date]
fixtures/manifest.md	FEATURE_DIR/fixtures/manifest.md	✅/❌	N lines	[date]
checklists/	FEATURE_DIR/checklists/	✅/❌	N files	[date]

For each artifact that exists, note whether it appears complete or truncated (does the last line look like a proper end-of-file or does it cut off mid-sentence?).

Phase 3: Task Progress Inspection

If tasks.md exists:

1. Parse task checkboxes:

   grep -c '\[x\]' FEATURE_DIR/tasks.md  # completed
   grep -c '\[ \]' FEATURE_DIR/tasks.md  # remaining
   grep -c '\[.\]' FEATURE_DIR/tasks.md  # total
   

2. Phase-by-phase breakdown:

   Phase	Total	Done	Remaining	Status
   Phase 1: Setup	N	N	N	✅/🔄/⏳
   Phase 2: Foundational	N	N	N	✅/🔄/⏳
   Phase 3: US1	N	N	N	✅/🔄/⏳
   ...

3. Inconsistent partial phase detection: If a phase has some [x] and some [ ] tasks, that phase is in progress. Report which phase is partially complete and which specific tasks remain.

4. Implementation evidence: For each completed [x] task, check if the referenced file path exists:

   # For each [x] task that mentions a file path:
   ls -la <file_path> 2>/dev/null || echo "MISSING"
   

   If a task is marked complete but the referenced file does not exist → INCONSISTENCY: flag as potential false completion.

Phase 4: Axiom Health Check

1. axiom_search({operation="status"}) — index status
2. axiom_search({operation="workspace_health"}) — orphans, unresolved relations

Report: index freshness, orphan count, any unresolved relations that match this feature's scope.

Phase 5: Test Evidence

If FEATURE_DIR/quickstart.md exists, run the applicable verification commands and report results:

# If backend work was in progress:
cd backend && source .venv/bin/activate && python -m pytest -v --co 2>/dev/null | tail -5
# If frontend work was in progress:
cd frontend && npm run test 2>/dev/null | tail -10

Report: test pass/fail counts, any regressions.

Phase 6: Produce Resume Snapshot (Optional Write)

If the user wants a bounded snapshot (they say "save state" or explicitly request), write specs/<feature>/resume.md:

#region Std.Opencode.ResumeSnapshot [C:2] [TYPE ADR] [SEMANTICS resume,snapshot,[DOMAIN]]
@BRIEF Workflow resume snapshot — current phase, completed items, remaining items, blockers.

**Feature**: [feature name]
**Branch**: [branch]
**Snapshot Date**: [DATE/TIME]

## Current Phase: [Phase Name]

## Completed
- Phase 1: Setup ✅ (N/N tasks)
- Phase 2: Foundational ✅ (N/N tasks)
- specs/xxx/contracts/modules.md ✅

## Remaining
- [ ] T017: Implement Core.Auth.Login (next task)
- [ ] Phase 3: US1 — N remaining tasks
- [ ] Phase 4: US2 — not started
- [ ] Phase N: Polish — not started

## Blockers
- [none / describe]

## Next Command
`/speckit.implement` — continue from Phase 3, task T017

## Verification Snapshot
- Backend tests: N passed, N failed
- Frontend tests: N passed, N failed
- Lint: clean / N warnings
- Axiom index: FRESH / STALE

#endregion Std.Opencode.ResumeSnapshot

This is the ONLY write this command may perform. All other operations are read-only.

Phase 7: Report

Output a concise resume report:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 speckit.resume — Feature State Recovery
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Feature: [feature name]
Branch: [branch]
Artifacts: N present, N missing

📊 Current Phase: [Phase Name]

✅ Completed:
   - Phase 1 Setup: N/N tasks
   - Phase 2 Foundational: N/N tasks
   - Contracts: modules.md, data-model.md

🔄 In Progress:
   - Phase 3 US1: N/N tasks done (task T017 next)

⏳ Not Started:
   - Phase 4 US2: N tasks
   - Phase 5 Polish: N tasks

⚠️ Blockers: [none / list]

📋 Exact Next Command:
   /speckit.implement — continue from Phase 3, task T017
   OR (if pre-implementation)
   /speckit.validate — run pre-implementation validation gate
   OR (if blocked)
   Resolve [blocker], then re-run /speckit.validate

📁 Uncommitted Changes: N files
💾 Axiom Index: FRESH / STALE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Behavior Rules

• NEVER mark tasks complete — this is read-only inspection.
• NEVER run create-new-feature.sh — the feature branch already exists.
• NEVER switch branches or modify git state.
• NEVER modify user changes — git status reports uncommitted work, preserve it.
• If no feature is detected (no spec.md, no feature branch), report: "No active feature detected. Run /speckit.specify to start a new feature."
• If the branch name does not match the FEATURE_DIR name, report the mismatch but do NOT resolve it automatically.
• If tasks.md is corrupt or unparsable, report the corruption and suggest re-running /speckit.tasks.