AGENT SKILL

self-retrospective

Turn what went wrong into a systemic fix. Use when the supervisor asks for a retro, after a failed task (mandatory), after a task with backtracks, or when wrapping up a multi-task session. Not the automated audit that runs after a session closes.

License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
self-retrospective
ai_hats
{ "type": "skill", "schema_version": 1 }
license
MIT
description
Turn what went wrong into a systemic fix. Use when the supervisor asks for a retro, after a failed task (mandatory), after a task with backtracks, or when wrapping up a multi-task session. Not the automated audit that runs after a session closes.

03 SKILL.md 正文

Self-Retrospective

Analyze completed or failed work to identify systemic improvements.

When to Use

  • When the supervisor explicitly asks to "write a retro" / "do a retrospective" — follow THIS protocol (4.5 filter, step-7 backlog gates); do not free-form a retro file by pattern-matching an existing one.
  • At the end of a multi-task work session (wrap-up across several closed tasks) — not only single-task completion.
  • After task completion (especially with failures or backtracks)
  • After a failed task (mandatory)
  • When the backlog manager transitions to review or failed state

Not the automated session-review loop. reflect-session (hats-reflect-session/v1) is a pipeline the harness runs to triage hypotheses/proposals; self-retrospective is the personal agent reflection you run by hand (free-form markdown, archived under sessions/retros/). And not a factual outcome record — that is task-summary; this skill is the improvement analysis (why the work went as it did, what to change next time).

Procedure

  1. Facts: Chronologically list all errors, backtracks, wasted iterations, or unexpected findings from the session.

  2. Classify: Assign each issue to a category:

    • Knowledge — missing context or incorrect assumption about the system
    • Environment — tooling, permissions, infrastructure issues
    • Process — skipped steps, wrong order, missing verification
    • Communication — misunderstood requirements, ambiguous instructions
    • Assumption — untested belief that turned out wrong
  3. Root Cause (5 Whys): For each significant issue, ask "Why?" iteratively until you reach an actionable root cause. Stop at the level where a fix is practical.

  4. Improvements: Propose specific, concrete changes:

    • Rule or skill updates (with exact content)
    • Workflow changes (with steps)
    • New checks or verification steps Focus on systemic fixes over one-off patches.

4.5 Hypothesis candidates: Surface improvements that describe a behavioural pattern (the agent systematically does X) — those go into the hypothesis backlog, not the task tracker. The supervisor chooses what to record.

Run the 5 sub-steps in order. Do not skip ahead — each gate exists
because skipping it produced a real class of HYP-backlog noise
(audit of HYP-001..026 found ~50% drop+merge waste — the baseline).

#### 4.5.a Filter — drop noise BEFORE formulating

Apply each criterion. The candidate survives only if ALL hold:

- **Recurrence or cost:** observed ≥2 times in this session, OR
  cost ≥5 minutes wasted, OR has at least one named adjacent
  flavor (sibling failure mode with the same shape).
- **Not already covered:** check the active-HYP set (from the
  session's evidence block, or `rack context HYP-NNN` per candidate)
  and verify no active HYP describes the same mechanism. If one does,
  the finding becomes evidence for that HYP via `ai-hats reflect
  issue` — but presented as a verdict contribution, not a new candidate.
- **Cause is hypothesised, not known:** if you can name the
  mechanism AND the fix with confidence, it belongs in the task
  tracker (step 7), not in HYP — HYP is for behavioural patterns
  whose cause is uncertain enough to need observation across
  sessions.

A finding that fails any criterion is **not** a HYP. Either drop
it, route it to step 7 (task card), or attach it as evidence to an
existing HYP. Single-instance one-off contexts almost always fail
the recurrence gate — most of the dropped HYPs in that
baseline were single-context (HYP-023, 024, 026).

#### 4.5.b Root-cause — chain to Step 3, do not restate

For every surviving candidate, take the 5 Whys output from Step 3
and walk it down until the answer is a **behaviour mechanism**,
not a behaviour description. Stop when the next "why?" would name
an environmental / system constraint outside the agent's control.

Mechanism = "rule X fires only in context Y because…",
            "agent generalises from prior Z without re-reading…",
            "agent treats each flavor as a one-shot lesson…"
NOT mechanism = "agent forgot to do X",
                "agent assumed X" (assumed *why*? keep asking).

Sanity check: if your CAUSE sentence is the same content as the
OBSERVATION sentence with different wording, you have not reached
the mechanism. Go one level deeper. (HYP-023 is the negative
example: cause text "agent assumes transition requires pre-merge"
sounded like a mechanism but was actually surface — the HYP was
refuted because the real mechanism was muscle-memory git-merge
reflex unrelated to FSM assumptions.)

#### 4.5.c Generalize — collapse to class

**Umbrella-first gate — ask this BEFORE you frame anything:**
do ≥2 surviving candidates share one root failure mode? If yes,
write **ONE** class-level HYP now that names each context as a
flavor. Do **not** file N atomic HYPs and leave the supervisor to
merge them (the HYP-043/044/045 → HYP-046 churn: three filings, all
stalled, replaced by one umbrella, two wasted CLI round-trips).

Lay all surviving candidates side-by-side. For any two (or more)
that share a mechanism, fold them into ONE class-level HYP that
names both contexts as flavors. Reference HYP-022 as the model:
one HYP, four named flavors of the same shell-quoting class.

Also re-scan active HYPs for class-level overlap — if your new
class-HYP is a generalisation of an existing narrow HYP, propose
superseding the narrow one rather than adding a third HYP.

#### 4.5.d Frame — present with concrete trace, not a one-liner

For each surviving candidate, write a block in this shape:

```
[N] OBSERVATION  (class-level: the behavioural pattern, NOT the instance)
    <one line naming the pattern the agent systematically exhibits>

    WHAT WENT WRONG (concrete trace, 3-7 lines)
    - <what the agent did, with specific commands / files / cites>
    - <what was expected instead>
    - <how it surfaced: error message, supervisor pushback, lost time>
    - <if class-level: name 2+ flavors observed or named>

    HYPOTHESISED CAUSE  (class-level mechanism)
    <mechanism from 4.5.b — one or two sentences>

    SCOPE
    single | class (list adjacent flavors)

    WHY RECORD
    <what evidence the observation window collects;
     what changes if confirmed vs refuted>
```

**Class-level framing rule.** The OBSERVATION (and the HYP title you
derive from it) and the HYPOTHESISED CAUSE must read as a *class* —
the pattern and its mechanism — never as the single trace you saw.
The concrete instance (this session's commands, files, the one
symptom) belongs ONLY in WHAT WENT WRONG. Litmus: if the OBSERVATION
line can be rewritten as "in <session/turn> the agent did <X>", it is
still instance-level — lift it one level before presenting.

- ✗ instance: «агент сообщил "zero blast radius" до конца прогона»
- ✓ class: «агент формулирует влияние изменения из guess, а не из
  evidence» — the "zero blast radius" trace moves into WHAT WENT WRONG

One-liner candidate lists are forbidden — the supervisor needs the
trace to decide keep/drop without re-reading the session log.

#### 4.5.e Confirm — supervisor decides, then act

Present the framed blocks. Ask: "Record as hypotheses? (all /
1,3 / none / discuss)". On confirmation, call `ai-hats reflect
issue` (one per item, `--bg` ok). Do NOT call before confirmation
— the HYP backlog is the supervisor's source of truth, not an
agentic auto-flush.

Skip 4.5 entirely if no findings survive 4.5.a.
  1. Quantify: "7 iterations wasted", "3 failed attempts before pivot" — numbers make the impact visible.

  2. Archive: Save report to <ai_hats_dir>/sessions/retros/YYYY-MM-DD-retro-<title>.md.

    Self-retros are personal agent reflections — free-form markdown is fine. They are NOT part of the automated feedback loop (reflect-session handles that via hats-reflect-session/v1).

  3. Backlog: For deferred improvements, create task cards via rack create (skill hatrack). Every identified improvement must either be fixed now or tracked.

Completion

  • Retrospective report saved to <ai_hats_dir>/sessions/retros/
  • Every improvement either applied or tracked as a task card
  • Quantified impact (wasted iterations, failed attempts)

Anti-Patterns

  • Vague findings ("things could be better") — be specific with numbers and examples
  • Only listing problems without root cause analysis — use 5 Whys
  • Skipping the backlog step — improvements that aren't tracked will be forgotten
  • Conflating a fix (concrete change → task card) with a pattern (behavioural tendency → reflect issue). If the wording is "do X", it's a fix; if it's "agent does X", it's a pattern.
  • Calling ai-hats reflect issue without the supervisor's confirmation — the hypothesis backlog is their source of truth, not an agentic auto-flush. Always present the candidate list and wait.
  • Skipping the 4.5.a filter and dumping every candidate at the supervisor — when the agent retracts after pushback ("на самом деле это шум"), the candidate failed the filter and should never have been presented. Run the filter first.
  • Restating the observation as the cause in 4.5.b — if your CAUSE sentence paraphrases the OBSERVATION, you stopped one "why?" short.
  • One-liner candidate presentation — Frame (4.5.d) demands a concrete trace. A line like "agent omits paths in tracker references" forces the supervisor to reconstruct context; the trace block makes the keep/drop call obvious.
  • Filing N narrow HYPs that share a mechanism — collapse to one class HYP at 4.5.c (umbrella-first gate). HYP-022 is the model (one HYP, four flavors); HYP-043/044/045 → HYP-046 is the anti-model.
  • Instance-level OBSERVATION / CAUSE — framing the candidate as the single trace you saw ("agent said 'zero blast radius' before the run finished") instead of the class ("agent states change-impact from guess, not evidence"). The instance belongs in WHAT WENT WRONG; the OBSERVATION and HYPOTHESISED CAUSE must be class-level (4.5.d).

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3