sdd-ship

SDD Ship — feature archival and lessons learned (Phase 4)

Ship closes the 5-phase SDD workflow: it turns a completed feature's working documents into a permanent archive with lessons learned, marks every phase document Shipped, and leaves the working folders clean for the next feature. Nothing ships unless the build is verifiably complete.

Contract

Naming rules (from the contracts): feature names are SCREAMING_SNAKE_CASE (e.g., USER_NOTIFICATIONS); the archive folder is .claude/sdd/archive/{FEATURE_NAME}/; the shipped file is SHIPPED_{YYYY-MM-DD}.md, dated with the ship date.

---

Verification order

Resolve completeness in this order before anything is archived:

┌─────────────────────────────────────────────────────────────────────┐
│  1. ARTIFACT VERIFICATION (confirm completeness)                     │
│     └─ Read: .claude/sdd/features/DEFINE_{FEATURE}.md                │
│     └─ Read: .claude/sdd/features/DESIGN_{FEATURE}.md                │
│     └─ Read: .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md           │
│     └─ Optional: .claude/sdd/features/BRAINSTORM_{FEATURE}.md        │
│                                                                      │
│  2. BUILD REPORT VALIDATION                                          │
│     └─ All tasks completed?                                          │
│     └─ All tests passing?                                            │
│     └─ No blocking issues?                                           │
│                                                                      │
│  3. CONFIDENCE ASSIGNMENT                                            │
│     ├─ All artifacts present + tests pass  → 0.95 → Ship             │
│     ├─ Artifacts present + minor issues    → 0.80 → Ask user         │
│     └─ Missing artifacts or failures       → 0.50 → Cannot ship      │
└─────────────────────────────────────────────────────────────────────┘

Ship Readiness Matrix

When NOT to ship

Any of these blocks the ship — stop and route back to /build:

• BUILD_REPORT shows incomplete tasks
• Tests are failing
• Blocking issues documented in the build report
• Missing required artifacts (DEFINE, DESIGN, BUILD_REPORT)

Ship only when all acceptance tests from DEFINE pass, the build report shows 100% completion, and no blocking issues remain.

---

Process

Step 1 — Verify completion

Read(.claude/sdd/features/DEFINE_{FEATURE}.md)
Read(.claude/sdd/features/DESIGN_{FEATURE}.md)
Read(.claude/sdd/reports/BUILD_REPORT_{FEATURE}.md)

# Verify build report shows success

Run the verification order above. Confidence below 0.85 → do not proceed.

Step 2 — Create archive folder

mkdir -p .claude/sdd/archive/{FEATURE_NAME}/

Step 3 — Copy artifacts to archive

cp .claude/sdd/features/DEFINE_{FEATURE}.md .claude/sdd/archive/{FEATURE}/
cp .claude/sdd/features/DESIGN_{FEATURE}.md .claude/sdd/archive/{FEATURE}/
cp .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md .claude/sdd/archive/{FEATURE}/

If Phase 0 was used, also archive the brainstorm:

cp .claude/sdd/features/BRAINSTORM_{FEATURE}.md .claude/sdd/archive/{FEATURE}/

Resulting archive structure:

.claude/sdd/archive/{FEATURE}/
├── BRAINSTORM_{FEATURE}.md  (if exists)
├── DEFINE_{FEATURE}.md
├── DESIGN_{FEATURE}.md
├── BUILD_REPORT_{FEATURE}.md
└── SHIPPED_{DATE}.md

Step 4 — Generate SHIPPED document

Compose the SHIPPED document following .claude/sdd/templates/SHIPPED_TEMPLATE.md — the template owns the format; do not improvise sections. It covers the summary, timeline, metrics, what was built, success-criteria verification against DEFINE, lessons learned, recommendations, and the archived-artifact list.

Step 5 — Update document statuses

Per WORKFLOW_CONTRACTS.yaml (status_transitions, trigger /ship completes), ship MUST update ALL phase documents to Shipped — this is the contract obligation that prevents stale "Ready for X" statuses:

Apply the updates to the archived copies (the working copies are removed in Step 6) and add a revision-history note to each:

Edit: archive/{FEATURE}/DEFINE_{FEATURE}.md
  - Status: → "✅ Shipped"
  - Add revision: "Shipped and archived"

Edit: archive/{FEATURE}/DESIGN_{FEATURE}.md
  - Status: → "✅ Shipped"
  - Add revision: "Shipped and archived"

Edit: archive/{FEATURE}/BUILD_REPORT_{FEATURE}.md
  - Status: → "✅ Shipped"

Step 6 — Clean up working files

rm .claude/sdd/features/DEFINE_{FEATURE}.md
rm .claude/sdd/features/DESIGN_{FEATURE}.md
rm .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md

If a BRAINSTORM was archived in Step 3, remove its working copy too:

rm .claude/sdd/features/BRAINSTORM_{FEATURE}.md

Step 7 — Save SHIPPED document

Write(.claude/sdd/archive/{FEATURE}/SHIPPED_{DATE}.md)

---

Lessons learned

Review all artifacts for insights and capture at least 2 specific lessons in these categories:

Rules for good lessons:

1. Don't skip this — lessons learned prevent future mistakes.
2. Be honest — document what didn't work too.
3. Be specific and actionable — "Better planning" → "Create architecture diagram before coding".
4. Archive everything — future you will thank present you.

Avoid vague lessons:

❌ "Better planning" (too vague)
❌ "More testing" (not specific)
❌ "Improved communication" (not actionable)

---

Quality Gate

Before saving the SHIPPED document:

PRE-FLIGHT CHECK
├─ [ ] All artifacts verified present (DEFINE, DESIGN, BUILD_REPORT)
├─ [ ] BUILD_REPORT shows all tasks complete
├─ [ ] All tests passing
├─ [ ] Acceptance tests from DEFINE verified
├─ [ ] No blocking issues in the build report
├─ [ ] Code deployed (if applicable)
├─ [ ] Archive directory created
├─ [ ] All artifacts copied to archive
├─ [ ] ALL archived documents' status updated to "✅ Shipped"
├─ [ ] At least 2 specific lessons documented
└─ [ ] Working files cleaned up from features/ and reports/

---

Close the cycle — end-of-cycle handoff

When the archive is complete, report closure to the user:

---

Anti-Patterns

---

References

• Template: .claude/sdd/templates/SHIPPED_TEMPLATE.md
• Contracts: .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml
• Executor: .claude/agents/workflow/ship-agent.md
• Entrypoint: .claude/commands/workflow/ship.md
• Previous phase: .claude/commands/workflow/build.md