Session Retrospective — Insight Discovery and Substrate Encoding

This skill enacts the Endogenous-First axiom from MANIFESTO.md: new knowledge discovered during a session must flow back into the substrate, not remain as ephemeral chat context. It is governed by AGENTS.md § Per-Phase Execution Checklists and § Session-End Closing Steps. This skill is the session-level enactment of Issue #82 (Dogma Neuroplasticity — back-propagation protocol).

Read docs/guides/session-management.md and docs/guides/workflows.md before deviating from any step below.

Beliefs & Context

This skill implements the back-propagation protocol: new patterns discovered interactively must be encoded durably before they can influence future sessions.

Implements: Issue #82 — Dogma Neuroplasticity — back-propagation protocol

Governed by:

• AGENTS.md § Per-Phase Execution Checklists — retrospective runs as the close step after the final phase
• MANIFESTO.md Endogenous-First axiom — endogenous knowledge compounds; chat-only knowledge evaporates

Used by:

• Executive Orchestrator (runs retrospective at session close)
• Executive Fleet (receives agent/skill encoding gaps)
• Executive Docs (receives AGENTS.md / guide encoding gaps)
• Orchestrator (commits via terminal after Review approval)
• Review agent (validates additions before commit)

Companion skill: session-management — retrospective runs during Session Close phase (Step 5 of that skill)

Encoding circuit — the complete back-propagation loop this skill enacts:

Sprint observation → Retrospective harvest → Gap-analysis → Routing plan → Issue seed → Workplan → Phase delegation → Commit

Steps 2–4 map to this skill's Harvest, Gap-Analyse, and Route steps; steps 5–8 execute in subsequent sessions from the routing plan. The circuit closes only when a commit lands — scratchpad notes alone do not close it. The highest-leverage point is step 3: a routing entry missing the Section field causes re-scoping at step 6 or 7, costing tokens that a complete entry at step 3 would have eliminated.

When to Run

Trigger this skill when any of the following conditions hold after a phase or session:

Do NOT run if:

• The context window is under pressure — write a ## Pre-Compact Checkpoint note and schedule the retrospective for the next session instead.
• The phase produced no new patterns (routine execution of a well-encoded procedure).
• You are mid-phase and the output is not yet stable.

Workflow

Step 1 — Harvest

Articulate what was learned this phase or session. Write a ## Retrospective — <YYYY-MM-DD> section in the active scratchpad (.tmp/<branch-slug>/<today>.md) with:

## Retrospective — YYYY-MM-DD

### Lessons Learned
1. <Lesson: one sentence — what happened and why it matters>
2. ...

### Anti-patterns Avoided
1. <What was tempting but skipped — and why it would have failed>

### Efficiency Observations
1. <What took longer than expected / shorter than expected — why>

Token target: ≤400 tokens for the Harvest section. Compress observations; do not include raw session history.

Inputs: scratchpad, workplan phase status, your own session memory. Output: a numbered lessons list with ≤10 items, written to the scratchpad.

Step 2 — Gap-Analyse

Delegate to an Explore subagent with a narrow, scoped prompt:

"For each lesson below, search AGENTS.md, docs/guides/, .github/agents/*.agent.md, and .github/skills/*/SKILL.md to identify whether it is already encoded. Return a table: Lesson | Already Encoded In | Gap (Yes/No). Return ≤800 tokens."

Pass the numbered lessons list as input. Do not pass the full scratchpad — Focus-on-Descent applies: narrow context in, compressed result out.

Expected output (from the Explore subagent):

The subagent appends its output under ## Gap-Analysis Output in the scratchpad.

Compression target: ≤800 tokens returned.

Step 3 — Route

For each lesson with Gap = Yes, route to the correct fleet agent using the Routing Table below. Write a ## Routing Plan section in the scratchpad listing each gap, its target agent, and the specific file(s) to update.

Routing Table

Constraint: route one gap per delegation. Do not batch all gaps into a single agent invocation — batching reduces accountability and makes Review harder. Each delegation gets a focused scope.

Routing entry format (for execution handoff across sessions): each row in the ## Routing Plan section should contain six fields:

| Gap# | Lesson (one sentence) | Target Agent | Target File | Section | Change (one sentence) |

A routing plan entry with these six fields is sufficient context to reconstruct a full delegation brief in a later session without re-reading session history. The Section field is the highest-value addition: without it, the receiving agent re-derives the insertion point at delegation cost. Grounded in 2026-03-13 corpus sprint: the 6-row routing plan from 2026-03-12 reconstructed all 6 Phase 4 delegations without re-derivation.

Inputs to each downstream agent: the specific lesson text + the target file(s) + the reasoning for the gap. Expected outputs: a file edit (new section, new bullet, or new file) ready for Review.

Step 4 — Verify

After all routing delegations complete, invoke the Review agent with:

"Review the following additions for consistency with existing substrate. Confirm each addition: (1) does not duplicate existing content, (2) follows the formatting conventions of its host file, (3) maintains cross-reference density (links back to MANIFESTO.md or AGENTS.md where applicable), (4) introduces no TODO placeholders."

Pass the list of changed files. The Review agent returns a per-file verdict.

If Review approves all changes, Orchestrator commits via git operations following Conventional Commits:

docs(session): encode <topic> lessons from <date> retrospective

If Review flags any change, fix before committing — do not bypass the Review gate.

Example Invocation Prompt

The canonical invocation for this skill is:

"What lessons have we learned? Delegate querying which ones are encoded and which aren't, routing to the fleet to update the executive orchestrator and appropriate workflows."

This phrase is the trigger. When an orchestrator uses this phrasing (or a close variant), apply this skill's four-step procedure in sequence.

Constraints

• Never encode lessons as chat-only notes. A lesson that exists only in conversation history will not survive compaction. Write it to the scratchpad first, then to the substrate.
• Never batch all lessons into one delegation. One gap → one delegation → one focused change → one Review checkpoint.
• Always run the Review gate before committing. Retrospective-sourced changes must be validated for consistency — they arrive from informal observation, not from a formal spec.
• Do not run under context-window pressure. If the context window is above 75%, write a ## Pre-Compact Checkpoint note (see session-management § Compaction Guard) and defer the retrospective to the next session open.
• Scope to genuine lessons. Do not encode obvious, already-documented behaviour. The bar is: "a future agent would behave differently if this were encoded."
• Do not modify MANIFESTO.md during a retrospective. That document encodes foundational axioms. Retrospectives update operational substrate (AGENTS.md, guides, skills, agent files) — not axioms.

Completion Criteria

The retrospective is complete when:

• ## Retrospective — <date> section written to active scratchpad
• Gap-analysis table produced (Explore subagent output in scratchpad under ## Gap-Analysis Output)
• All Yes-gap lessons routed to correct fleet agents, one per delegation
• Each delegated agent has produced a file edit
• Review agent has returned Approved verdict for all changed files
• Orchestrator has committed with a Conventional Commit message referencing the retrospective date
• Session summary notes that retrospective was run and which gaps were filled