npx claudepluginhub flox/forge-plugin --plugin forgeCapture a retrospective note about Forge workflows, tools, or processes.
Quick way to capture correction moments and feedback during development work. Automatically routes notes based on where you are working, not on the content of the note:
artifacts/retrospective-notes.mdartifacts/retrospective-notes.md.forge-context/artifacts/ retrospective-notes.md/forge:retro-note
No arguments — the command will interactively capture the note.
When using bash commands:
test -d or [ -d ] before cd or directory opstest -f or [ -f ] before file operationsCapture a note when you encounter:
Detect location using these checks:
# Current directory
pwd
# Current branch
git branch --show-current
# List worktrees
git worktree list
Priority order:
Active slice worktree: If the current directory
is within a worktree AND a slice directory exists
under .forge-context/slices/YYYYMM-*/:
{slice_path}/artifacts/retrospective-notes.mdActive effort worktree: If current directory is
within a worktree AND on an effort/* branch:
ls {worktree}/.forge-context/efforts/YYYYMM-*/{effort_path}/artifacts/retrospective-notes.mdSlice directory (not in worktree): If cwd matches
.forge-context/slices/YYYYMM-*/:
{slice_path}/artifacts/retrospective-notes.mdEffort directory: If cwd matches
.forge-context/efforts/YYYYMM-*/:
{effort_path}/artifacts/retrospective-notes.mdNo context (on main or elsewhere):
.forge-context/artifacts/retrospective-notes.md1. What happened (REQUIRED):
2. Recommendation (optional):
3. Additional context (optional):
Auto-generate title:
REQUIRED GATE: Read the target file before any modification. This finds the next note number AND verifies existing content is present before appending.
Read target retrospective-notes.md:
### Note N: entriesCRITICAL: Always use the Edit tool to append the note. Never use the Write tool for existing files — it will overwrite all existing notes.
Standard note format:
## {YYYY-MM-DD}: General
### Note {N}: {Auto-generated title from "What happened"}
<!-- STATUS: UNPROCESSED -->
**What happened:**
{Full description}
**Recommendation:**
{Recommendation if provided, or "See description"}
**Additional context:**
{Additional context if provided}
---
Field rules:
Appending with the Edit tool:
Find the last --- separator in the file, then append
the new note after it:
old_string: "---\n" (the final separator)
new_string: "---\n\n## {date}: General\n\n### Note {N}:..."
If file doesn't exist, create it with a header then add the note content.
If in a worktree, commit the change:
git add {target_file_path}
git commit -m "docs: Add retrospective note - {brief_title}
Captured correction moment for future workflow improvements.
Co-Authored-By: Claude <noreply@anthropic.com>"
For slice/effort directories on main, no separate commit is needed — the note is added to existing uncommitted work.
Show confirmation:
"Retrospective note added to {context_name}."
"Note #{N}: {title}"
"This note will be processed via
/forge:improvefor workflow improvements.""Location: {file_path}"
If note was committed, offer to push and PR if needed.
User: /forge:retro-note
Agent: No active slice/effort context detected.
Adding note to .forge-context/artifacts/.
What happened?
User: The designer agent didn't detect our custom
test runner — it assumed pytest but we use
cargo nextest.
Agent: What change might improve this?
User: Add a test runner detection step to the
designer agent.
Agent: Any additional context?
User: This was during implementation phase.
Agent: Retrospective note added.
Note #1: The designer agent didn t detect
custom test runner
Location: .forge-context/artifacts/retrospective-notes.md
User: /forge:retro-note
Agent: Detected active slice: Environment SBOMs
What happened?
User: Had to look through multiple files to find
which command to use
Agent: What change might improve this?
User: Add quick command reference to CLAUDE.md
Agent: Any additional context?
User: [presses enter]
Agent: Retrospective note added to Environment SBOMs.
Note #2: Had to look through multiple files
| Command | Purpose |
|---|---|
/forge:improve | Process and apply retrospective notes |
/forge:audit | Check for unprocessed notes |