retrospect

Files (9)

• SKILL.md
• audit-distribution-gates.py
• carried-task-scan.py
• appendices.md · references/
• report-template.md · references/
• stage1-2-analysis.md · references/
• stage2.5-audit.md · references/
• stage3-reporting.md · references/
• stage4-execution.md · references/

SKILL.md (first lines)

# Retrospect

## Overview

Repeated friction wastes cycles across sessions. Unexamined pain stays unresolved.

**Core principle:** ALWAYS analyze root cause before proposing any action.
Symptom-level fixes miss the underlying pattern.

**Pipeline:** `Load -> Hygiene -> Analyze -> Audit -> Report/Approve -> Execute`

**Delegates to:** `oh-my-claudecode:tracer` agent (causal pattern analysis),
`oh-my-claudecode:analyst` agent (pattern clustering) — invoked via
`Agent(subagent_type="oh-my-claudecode:...")`

**Prerequisites:** `oh-my-claudecode` must be installed. The tracer and
analyst calls in Stage 2 have no fallback, which is why this skill sits in
the Enhanced tier of the compatibility table (`README.md`), not Standalone.

**Reference map:**

- Stage 1 / 1.5 / 2 / 2.7 details: [`references/stage1-2-analysis.md`](references/stage1-2-analysis.md)
- Stage 2.5 gate procedures: [`references/stage2.5-audit.md`](references/stage2.5-audit.md)
- Stage 3 output contract and approval flow: [`references/stage3-reporting.md`](references/stage3-reporting.md)
- Stage 3 worked examples: [`references/report-template.md`](references/report-template.md)
- Stage 4 execution procedures: [`references/stage4-execution.md`](references/stage4-execution.md)
- Rationalization catalog / red flags / full failure matrix: [`references/appendices.md`](references/appendices.md)

## The Iron Law

```
NO ACTION WITHOUT ROOT CAUSE ANALYSIS FIRST.
PATTERN ≠ ROOT CAUSE. SYMPTOM ≠ ROOT CAUSE.
REPEATED PATTERN + MEMORY = FAILED REMEDY. ESCALATE.
TRACER + ANALYST CALLS ARE MANDATORY, NOT OPTIONAL.
```

If you have not completed Stage 2 (Analyze), you cannot propose actions.

## When to Use

Use at the END of a working session to extract learnings:

- Session had repeated tool retries or direction changes
- User gave corrections mid-session
- A task took significantly longer than expected
- Workflow steps were skipped or out of order
- User expressed frustration or redirected multiple times

Use this especially when the same mistake happened more than once, when you
feel "I should have done that differently", or when a new workflow pattern
emerged that is not captured anywhere.

## The Stages

You MUST complete each stage before proceeding to the next.

1. **Stage 1: Load Calibration Standard**
Read the governing rule files and turn them into concrete scan questions.

2. **Stage 1.5: MEMORY.md Hygiene Pass (Detect-only)**
Run the bounded hygiene scan before the conversation analysis. It is
unconditional.

3. **Stage 2: Analyze Conversation**
Run the symmetric pre-scan lanes, derive root causes, and assign preliminary
actions.

4. **Stage 2.5: Action Distribution Audit**
Run the gate suite before any Stage 3 output.

5. **Stage 3: Report + Approval**
Emit the canonical report shape, carry caveats forward, run the pre-output
falsification gate, then ask for per-finding approval.

6. **Stage 4: Execute**
Run only approved actions, then verify the resulting artifacts.

### Stage 1: Load Calibration Standard

Before scanning the conversation:

1. Read global and project rule files — load large files (a packaged `SKILL.md`
   can exceed ~1500 lines) in bounded section/line-range chunks, never a single
   broad read that can truncate and silently drop tail rules (see
   [`references/stage1-2-analysis.md`](references/stage1-2-analysis.md)).
2. Identify the rule categories you will scan against.
3. Turn each category into a calibration question.

Use [`references/stage1-2-analysis.md`](references/stage1-2-analysis.md)
before doing the actual scan. That reference is the full procedure for Stage 1,
Stage 1.5, Stage 2, and Stage 2.7.

### Stage 1.5: MEMORY.md Hygiene Pass (Detect-only)

Stage 1.5 runs unconditionally between Stage 1 and Stage 2. It surfaces latent
MEMORY.md defects that the session-scoped friction scan cannot see.

**Mandatory shape:**

- Scan up to **5 feedback files per invocation**
- Persist progress at `.omc/state/retrospect-hygiene-cursor.json`
- Emit findings with `category: memory_hygiene`
- Never mutate MEMORY.md here — Stage 1.5 is detect-only

**Five detection signals:**

1. stale reference
2. contradiction
3. merge candidate
4. size threshold
5. missing oracle annotation

**Cursor read mandate (entry — MUST run first):**

- Use `next_batch_pointer` to choose the batch start
- Exclude `scanned_recent_batch`
- Carry forward the cursor `note` into Stage 3 input
- Run `carried-task-scan.py` over the cursor and emit every candidate it prints

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis