/carryforward Command

Analyze the just-completed phase and update the living CONSIDERATIONS.md document with institutional knowledge.

Role & Mindset

You are a senior engineer conducting a phase retrospective. Your job is to extract the most valuable insights from completed work and preserve them for future phases. Be ruthlessly selective - only the most impactful lessons deserve space in this document.

Your Task

Review the completed phase, extract key insights, and update .spec_system/CONSIDERATIONS.md while maintaining the strict 600-line limit. This document serves as institutional memory for AI assistants working on future phases.

When to Run

Run /carryforward after completing a phase, before starting /phasebuild for the next phase. This is optional but recommended for:

• Phases with significant technical discoveries
• Phases where you encountered and solved novel problems
• Phases with decisions that affect future work
• Any phase over 4 sessions

Steps

1. Verify Phase Completion

Check .spec_system/state.json:

• Confirm current phase status is "complete"
• Get phase number and name
• If phase not complete, inform user and exit

2. Gather Phase Artifacts

Read all implementation summaries from the completed phase:

# Find all IMPLEMENTATION_SUMMARY.md files for completed phase
ls .spec_system/archive/phases/phase_NN_*/IMPLEMENTATION_SUMMARY.md

Also review:

• .spec_system/audit/ - recent audit reports
• .spec_system/PRD/phase_NN/ - phase requirements (before archive)
• Any implementation-notes.md files with blockers or discoveries

3. Extract Insights

From each session's IMPLEMENTATION_SUMMARY.md, identify:

Active Concerns (things that affect upcoming work):

• Unresolved technical debt
• Known limitations or constraints
• External dependencies with risks
• Performance thresholds to monitor
• Security considerations

Lessons Learned (patterns to follow or avoid):

• Technical decisions that worked well (and why)
• Approaches that failed (and why)
• Useful patterns discovered
• Tool/library insights
• Architecture insights

Items to Resolve (move from Active Concerns if addressed):

• Check if previous Active Concerns were addressed this phase
• Move them to Resolved with brief resolution note

4. Read Current CONSIDERATIONS.md

Read .spec_system/CONSIDERATIONS.md:

• Parse existing sections
• Note current line count
• Identify stale items in each section

5. Update Document

Update .spec_system/CONSIDERATIONS.md following the format below.

Rules for updates:

1. Active Concerns: Add new, remove resolved, keep max 20 items
2. Lessons Learned: Add new, merge similar, keep max 30 items
3. Resolved: Add newly resolved, rotate out items older than 2 phases (keep max 15 items)
4. Total line limit: 600 lines STRICT - trim older/less relevant items if needed
5. Conciseness: Each item should be 1-3 lines max
6. Context: Include phase number where item originated

6. Report Summary

Tell the user what was updated.

CONSIDERATIONS.md Format

# Considerations

> Institutional memory for AI assistants. Updated between phases via /carryforward.
> **Line budget**: 600 max | **Last updated**: Phase NN (YYYY-MM-DD)

---

## Active Concerns

Items requiring attention in upcoming phases. Review before each session.

### Technical Debt
<!-- Max 5 items -->

- [P05] **Item name**: Brief description of the concern and why it matters.

### External Dependencies
<!-- Max 5 items -->

- [P08] **Item name**: Brief description of risk or constraint.

### Performance / Security
<!-- Max 5 items -->

- [P11] **Item name**: Threshold or requirement to monitor.

### Architecture
<!-- Max 5 items -->

- [P03] **Item name**: Constraint or consideration for design decisions.

---

## Lessons Learned

Proven patterns and anti-patterns. Reference during implementation.

### What Worked
<!-- Max 15 items -->

- [P02] **Pattern name**: What it is and when to use it.

### What to Avoid
<!-- Max 10 items -->

- [P04] **Anti-pattern name**: What went wrong and why to avoid.

### Tool/Library Notes
<!-- Max 5 items -->

- [P07] **Tool name**: Key insight about usage or configuration.

---

## Resolved

Recently closed items (buffer - rotates out after 2 phases).

| Phase | Item | Resolution |
|-------|------|------------|
| P10 | Item name | How it was resolved |
| P09 | Item name | How it was resolved |

---

*Auto-generated by /carryforward. Manual edits allowed but may be overwritten.*

Line Budget Guidance

Target allocation within 600 lines:

• Header/metadata: ~15 lines
• Active Concerns: ~150 lines (20 items x ~7 lines avg)
• Lessons Learned: ~250 lines (30 items x ~8 lines avg)
• Resolved: ~100 lines (15 items in table)
• Section headers/spacing: ~85 lines

Trimming Strategy

When approaching 600 lines, trim in this order:

1. Resolved items older than 2 phases
2. Lessons Learned items older than 5 phases (unless still highly relevant)
3. Active Concerns that have become irrelevant
4. Merge similar items within sections
5. Shorten verbose descriptions

Output

Phase NN Carryforward Complete

Updated .spec_system/CONSIDERATIONS.md:
- Active Concerns: +N new, -N resolved, N total
- Lessons Learned: +N new, N total
- Resolved: +N added, -N rotated out, N total
- Line count: NNN/600

Key additions:
- [Active] Brief description
- [Lesson] Brief description

Ready for /documents to maintain project documentation.

Error Handling

If CONSIDERATIONS.md doesn't exist:

CONSIDERATIONS.md not found.

This file should be created by /initspec. Creating from template...
[Creates file using template from initspec]

If phase not complete:

Cannot run /carryforward.

Current phase (NN) status: [status]
Complete all sessions and run /validate on final session first.

If no insights found:

Phase NN Review Complete

No significant insights identified for carryforward.
CONSIDERATIONS.md unchanged.

This is fine for straightforward phases. Proceed with /phasebuild.