Extract lessons learned and update CONSIDERATIONS.md between phases
Updates institutional knowledge document with key insights and lessons from completed phases.
/plugin marketplace add moshehbenavraham/apex-spec-system/plugin install apex-spec@apex-spec-marketplaceAnalyze the just-completed phase and update the living CONSIDERATIONS.md document with institutional knowledge.
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.
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.
Run /carryforward after completing a phase, before starting /phasebuild for the next phase. This is optional but recommended for:
Check .spec_system/state.json:
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)implementation-notes.md files with blockers or discoveriesFrom each session's IMPLEMENTATION_SUMMARY.md, identify:
Active Concerns (things that affect upcoming work):
Lessons Learned (patterns to follow or avoid):
Items to Resolve (move from Active Concerns if addressed):
Read .spec_system/CONSIDERATIONS.md:
Update .spec_system/CONSIDERATIONS.md following the format below.
Rules for updates:
Tell the user what was updated.
# 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.*
Target allocation within 600 lines:
When approaching 600 lines, trim in this order:
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.
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.