retrospective · diff
git:20260610.be2a852 to git:20260610.c15894f
289 added, 4 removed. Audit A to A.
---
name: retrospective
description: Store a learning — classify type, route to canonical destination. Use after discoveries, unexpected issues, workarounds, or when a reusable pattern emerges.
effort: low
keywords: [learning, pattern, discovery, workaround, knowledge]
task_strategies: [feature, bug-fix, refactor, spike]
stream_affinity: [roadmap, tech-debt, research]
argument-hint: "[learning text]"
group: learning
model: haiku
allowed-tools:
- Bash
- Read
- Write
- Glob
- Grep
- AskUserQuestion
- mcp__ruflo__memory_search
- ToolSearch
status: stable
growth_stage: evergreen
---
+ # Retrospective
- <!-- PROCEDURE_FILE: procedures/retrospective.md -->
- This skill's full procedure is in a separate file for startup performance (ADR-034).
- Read and execute `../../procedures/retrospective.md` resolved against this skill's base directory (the path announced when the skill loads) — i.e. `{base-dir}/../../procedures/retrospective.md`. This form is valid in both the repo layout and the deployed-plugin layout.
- If the path doesn't resolve, use Glob to find `**/procedures/retrospective.md`.
+ Store a learning in the memory taxonomy. Classifies the input by type, then routes
+ to the canonical destination. No ruflo dependency — flat files are primary.
+
+ Spec: [memory-taxonomy-ddd.md](../../../docs/architecture/features/memory-taxonomy-ddd.md)
+ [memory-taxonomy-sdd.md](../../../docs/architecture/features/memory-taxonomy-sdd.md)
+
+ ---
+
+ <!-- ruflo preamble -->
+ ToolSearch("select:mcp__ruflo__memory_search")
+
+ ## Step 1 — Collect the learning
+
+ If `$ARGUMENTS` is non-empty, use it as the learning text. Otherwise ask:
+ > "What did you learn? Describe the situation and the finding."
+
+ ---
+
+ ## Step 2 — Classify
+
+ Apply the decision tree in order. Stop at first match.
+
+ ```
+ 1. Is this ephemeral — only useful for resuming this session?
+ → Session state (skip retrospective; write via session-end hook)
+
+ 2. Does this say "always X" or "never Y" with no context needed to apply it?
+ → Rule
+
+ 3. Is this a why-we-chose-X architectural or strategic choice with explicit tradeoffs?
+ → Decision
+
+ 4. Is this a pointer to where something lives in an external or cross-project system?
+ → Reference
+
+ 5. Is this a reusable solution to a recurring problem shape?
+ → Pattern
+
+ 6. Everything else — domain understanding, research finding, conceptual model
+ → Knowledge
+ ```
+
+ Set `type`, `destination`, and `gate` (auto | human) from the table:
+
+ | Type | Destination | Gate |
+ |------|------------|------|
+ | Rule | `system/rules/` — draft only, human places | human |
+ | Decision | `docs/architecture/decisions/ADR-NNN-*.md` — stub, human commits | human |
+ | Reference | `~/.claude/memory/portfolio.md` | auto |
+ | Pattern | `~/.claude/projects/{project}/memory/pattern_{slug}_{date}.md` | auto (after transferability filter) |
+ | Knowledge | `~/.claude/memory/knowledge-staging.md` | auto |
+ | Session | native memory dir — skip, handled by session-end | auto |
+
+ **Tie-breaking:** If two types are plausible, prefer lower-gate type (Pattern over Rule).
+ Note the ambiguity in the draft so the user can override.
+
+ ---
+
+ ## Step 3 — Format the draft
+
+ ### Rule draft
+
+ ```markdown
+ <!-- Draft rule — review, adjust, then place in system/rules/{name}.md -->
+ # {Rule Name}
+
+ {directive: "Always X" or "Never Y" — one sentence, no context needed to apply}
+
+ **Why:** {the incident or principle that established this}
+ **How to apply:** {when this fires, edge cases}
+ ```
+
+ ### Pattern draft
+
+ **Before drafting**, apply the transferability filter:
+ > *"Would this pattern apply if I were working on a completely different codebase with a different client?"*
+ - **No** → reclassify as Knowledge or field note. Do not use the pattern destination.
+ - **Borderline** → proceed with `confidence: 0.4`
+ - **Yes** → proceed with `confidence: 0.5`
+
+ ```markdown
+ ---
+ name: {pattern-name-slug}
+ description: {one-line summary — used to decide relevance in future sessions, be specific}
+ metadata:
+ type: pattern
+ confidence: {0.5 | 0.4 for borderline}
+ source_task: {task-id or "manual-{YYYY-MM-DD}"}
+ created: {YYYY-MM-DD}
+ transferable: true
+ ---
+
+ **Problem:** {one sentence — the situation that triggers this pattern}
+ **Solution:** {what to do, concrete enough to apply without context}
+ **Why:** {evidence — past incident, test result, or principle}
+ ```
+
+ ### Knowledge draft
+
+ ```markdown
+ ## {topic-slug}
+
+ **Claim:** {the knowledge — a fact, model, or finding}
+ **Source:** {doc, session, or external ref}
+ **Confidence:** {low | medium | high}
+ **Added:** {today}
+ **Promote to:** {path/to/dimension-doc.md | portfolio.md | MEMORY.md}
+ **Promoted:** —
+ ```
+
+ ### Decision draft (ADR stub)
+
+ ```markdown
+ # ADR-NNN: {title}
+
+ **Status:** Proposed
+ **Date:** {today}
+
+ ## Context
+ {why this decision was needed}
+
+ ## Decision
+ {what was decided}
+
+ ## Consequences
+ {tradeoffs accepted}
+
+ ## Non-actions
+ {what was explicitly ruled out}
+ ```
+
+ ### Reference draft
+
+ One-line entry for `portfolio.md`:
+ ```
+ - {system name}: {what it contains / why it matters} — {URL or path}
+ ```
+
+ ---
+
+ ## Step 4 — Cap check (auto-gate types only)
+
+ Before writing, check destination capacity:
+
+ **Pattern — dedup check (replaces cap):**
+ ```
+ mcp__ruflo__memory_search(query: "{pattern problem + solution summary}", namespace: "pattern", limit: 1, threshold: 0.85)
+ ```
+ - Similarity ≥ 0.85: near-duplicate exists — skip write, note the existing key.
+ - No match / MCP unavailable: proceed to write.
+ No cap, no pruning. Per-pattern files scale without maintenance overhead.
+
+ **knowledge-staging.md:**
+ ```bash
+ count=$(grep -c "^## " ~/.claude/memory/knowledge-staging.md 2>/dev/null || echo 0)
+ ```
+ - ≥20: warn "knowledge-staging.md at {N}/30 — run `/brana:memory review` to promote stale entries"
+ - =30: block. Require promotion or deletion of ≥1 entry first.
+
+ **MEMORY.md (for Reference type):**
+ ```bash
+ count=$(wc -l < ~/.claude/projects/-home-martineserios-enter-thebrana-thebrana/memory/MEMORY.md 2>/dev/null || echo 0)
+ ```
+ - ≥180: warn "MEMORY.md at {N}/200 lines"
+ - ≥195: block. No new entries until trimmed.
+
+ ---
+
+ ## Step 5 — Write (or gate)
+
+ ### Human-gated types (Rule, Decision)
+
+ ```
+ AskUserQuestion:
+ question: "Classified as {type}. Review the draft and confirm routing."
+ header: "Memory routing"
+ options:
+ - label: "Approve — {type} → {destination} (Recommended)"
+ description: "Accept the classified type and route to the suggested destination."
+ - label: "Override type → Pattern"
+ description: "Reclassify as Pattern and route to pattern memory."
+ - label: "Override type → Knowledge"
+ description: "Reclassify as Knowledge and route to knowledge staging."
+ - label: "Skip — don't store"
+ description: "Discard this learning — don't store anywhere."
+ ```
+
+ On "Approve":
+ - **Rule:** Display the draft text. Instruct: "Place this in `system/rules/{name}.md` and commit it yourself. I won't auto-write to rules/."
+ - **Decision:** Write the ADR stub to `docs/architecture/decisions/ADR-NNN-{slug}.md` (next available NNN). Instruct: "Review the stub, adjust, and commit."
+
+ ### Auto-gated types (Pattern, Knowledge, Reference)
+
+ Write `draft` content to destination:
+
+ **Pattern → `~/.claude/projects/{project-hash}/memory/pattern_{slug}_{YYYY-MM-DD}.md`:**
+
+ Write the draft (with frontmatter) to a new per-pattern file. Use Write tool.
+ Activate the sentinel first so `feedback-gate.sh` passes through:
+ ```bash
+ touch /tmp/brana-close-active
+ # ... write pattern file ...
+ rm -f /tmp/brana-close-active
+ ```
+
+ Do NOT append to MEMORY.md. Pattern files are findable via ruflo semantic search.
+ MEMORY.md entries are added only at explicit human promotion (recurrence ≥ 3 sessions).
+
+ **Knowledge → `~/.claude/memory/knowledge-staging.md`:**
+ ```bash
+ if [ ! -f ~/.claude/memory/knowledge-staging.md ]; then
+ echo "# Knowledge Staging" > ~/.claude/memory/knowledge-staging.md
+ echo "" >> ~/.claude/memory/knowledge-staging.md
+ echo "<!-- cap: 30 | warn-at: 20 | stale-after: 30 days -->" >> ~/.claude/memory/knowledge-staging.md
+ fi
+ ```
+ Prepend the draft after the file header.
+
+ **Reference → `~/.claude/memory/portfolio.md`:**
+ Append the one-line entry to the appropriate section. If section not found, append to end.
+
+ ---
+
+ ## Step 6 — Fallback chain
+
+ If a destination is unavailable (file locked, dir missing, write denied):
+
+ ```
+ Pattern fallback: if project memory dir missing → write to ~/.claude/memory/pattern_{slug}_{date}.md
+ Knowledge fallback: knowledge-staging.md → MEMORY.md inline with [KNOWLEDGE] prefix
+ Reference fallback: portfolio.md → MEMORY.md inline
+ Rule/Decision: no fallback — human-gated, display draft only
+ ```
+
+ Log any fallback to `~/.claude/memory/fallback-log.md`:
+ ```
+ {date} | {type} | intended: {destination} | actual: MEMORY.md | reason: {error}
+ ```
+
+ ---
+
+ ## Step 7 — Confirm
+
+ Report what was stored and where:
+ ```
+ Stored: {type} → {destination}
+ Title: {pattern/knowledge/decision title}
+ Gate: {auto | human-approved | human-display-only}
+ ```
+
+ ---
+
+ ## Step 8 — Promotion tracking (patterns only)
+
+ After storing, check if any patterns recalled this session warrant promotion.
+
+ Search per-pattern files for low-confidence entries:
+ ```bash
+ grep -rl "confidence: 0\.[45]" ~/.claude/projects/{project-hash}/memory/pattern_*.md 2>/dev/null
+ ```
+
+ For each recalled pattern that **was useful** this session:
+ - Note the recall mentally. If a pattern has been recalled and useful ≥3 sessions: surface it for promotion.
+ - Promotion path: user approves → create `feedback_{slug}.md` + add entry to MEMORY.md
+ (always-loaded tier). Update the per-pattern file frontmatter: `confidence: 0.7`.
+
+ For each recalled pattern that **was harmful or misleading**:
+ - Update the per-pattern file frontmatter: `confidence: 0.2` (suspect).
+
+ **Skip this step** if no patterns were recalled or user wants to skip.
+
+ ---
+
+ ## Step 9 — Backup
+
+ ```bash
+ "$HOME/.claude/scripts/backup-knowledge.sh" 2>/dev/null || true
+ ```
+
+ ---
+
+ ## Rules
+
+ - **Placement in `system/rules/` is always manual.** Display draft, instruct user. Never write there automatically.
+ - **All learnings route through the taxonomy.** No catch-all files; no feedback_ prefix files.
+ - **Never overwrite per-pattern files.** Each pattern is its own file; knowledge-staging.md is append-only.
+ - **Classify honestly.** When uncertain, prefer Pattern over Rule (lower gate = fewer blockers).
+ - **Ask for clarification** if the learning is ambiguous — don't guess the type.