Planner Reflect

---
name: planner-reflect
description: >
  This skill should be used when the user invokes /plan-reflect, says
  "reflect on the plan", "what did we learn", "post-mortem the planning",
  or in russian «отрефлексируй», «что пошло не так»,
  «обнови контекст планнера», «сверь план с фактом».
  Activates after a session that ran /plan-do or otherwise produced a
  PLANNER_OUTPUT.md. Compares plan against reality using five evidence
  sources and updates planner-context.md with four learning types:
  gap-fill, model-strength signals, user-correction patterns, and
  cost-calibration deltas. Always emits a "Lessons learned" section,
  even if empty, as a force-function for honest retrospection.
---

# Planner-Reflect — post-task learning

This skill compares what was planned against what actually happened, extracts lessons, and writes them back into `<project-root>/.claude/planner-context.md` so the next planning session starts smarter. It is the feedback loop that closes the gap described in feature README §35-44: plans drift from reality, gaps in the agent catalog go unnoticed, weak-model signals are forgotten, user corrections evaporate after the session ends. Run this skill explicitly via `/plan-reflect`, ideally in the same session as the work it reflects on — cross-session transcript availability is not guaranteed and the skill degrades gracefully if it is missing.

The run is short and linear: gather the five evidence sources, classify findings into the four update types, mask any PII in the proposed additions, write the result to `planner-context.md`, and emit a chat summary that always includes a "Lessons learned" block. There is no looping, no escalation, and no chaining into other skills — reflection is observation, not action.

## Inputs (5 evidence sources)

The skill reads exactly five sources, in this order. Each source is independent; missing one weakens the conclusions but does not block the run.

1. **`<feature-dir>/PLANNER_OUTPUT.md`** — the original plan: phases, agents chosen, model picks, cost estimate. Read with `Read`. This is the ground truth for "what was planned"; if it is missing, the skill exits (see next section).
2. **`git log --oneline <since-plan>..HEAD`** — actual commits made since the plan was written. Use `Bash(git log …)` constrained to git only. Compare commit subjects and files-touched against the plan's phases to spot scope creep, dropped phases, or unplanned files.
3. **Review files under `<feature-dir>/review-request-changes/`** — defects raised during the session, their severity tags, and the files they pointed at. Use `Glob` for discovery and `Read` for content. High-severity recurring defect categories feed §6 (user-corrections) and §4 (model-strength).
4. **Agent transcripts via `TaskGet` / `TaskOutput`** — used to detect retry/escalate patterns inside subagent runs (e.g. "test failed → fix → still failed → escalate"). Current-session-only by default; treat cross-session calls as best-effort and do not assume reachability.
5. **User messages from the current session** — explicit corrections such as «не делай сам», «это неправильно», «переделай», «не лезь сам в код». Source: the live conversation transcript visible to the skill at runtime.

## When evidence is missing

The skill must not fail loudly when an input source is missing — the reflection loop should produce *some* signal whenever it runs, even if degraded. The rules below cover the four common cases.

- **No `PLANNER_OUTPUT.md`** → exit gracefully with the message `nothing to reflect on; run /plan first`. Do not fail, do not write a half-formed lesson, do not invent a plan from git history.
- **No transcripts** (cross-session call, tool unavailable, or future Claude Code semantics changing) → degrade to git-diff plus review-files only. Label the output explicitly: `transcript-based learnings unavailable`. The four update types remain available; only the model-strength signal weakens because retry-loops are no longer directly observable.
- **No git history since the plan** → likely the plan was never executed; emit `plan exists but not yet executed; nothing to reflect` and stop without writing.
- **Partial evidence** (some sources present, others missing) → proceed with what is available, and note in the chat summary which sources were unavailable so the user can judge the strength of the conclusions before acting on them.

## The 4 update types

Each update type has a trigger (when the skill should produce it), a recording format (exactly what gets written), a destination section in `planner-context.md`, and a tone-rule (the wording discipline that prevents categorical or accusatory statements). Skip a type entirely if its trigger does not fire for this session — empty is better than fabricated.

### 4.1 gap-fill

- **Trigger** — the orchestrator used `general-purpose` where `planner-context.md` §1 had a `❌ GAP` flag for the relevant stack, OR a stack appeared during the session that was not even flagged in the catalog.
- **Record** — for an existing flag, append `<!-- gap-confirmed YYYY-MM-DD from FEAT-NNNN -->` to the gap row. For a newly discovered stack, add a new gap row in the format `❌ GAP (<stack>, <variant>) — fallback: general-purpose <!-- discovered YYYY-MM-DD from FEAT-NNNN -->`.
- **Destination** — §1 of `planner-context.md` (Каталог агентов).
- **Tone** — neutral and factual: describe the missing role, do not blame the orchestrator. The gap is a property of the catalog, not a failure of the run.

### 4.2 model-strength

- **Trigger** — transcripts (or git-log of repeat commits on the same files) show retry-loops, failed test cycles, or explicit escalation. Cost-actuals also feed here when they correlate with retry patterns.
- **Record** — a sentence in the form «for tasks of type X on this project, model Y was weak → consider model Z». Always tie the observation to (a) **task type**, (b) **this project**, (c) the **FEAT-id** as evidence anchor.
- **Destination** — §4 of `planner-context.md` (Таблица моделей), as a sub-bullet under the relevant model row.
- **Tone-rule (non-negotiable, README Edge-Case row 9)** — never write categorical statements like «Sonnet bad» or «Haiku unreliable». A model is weak *for a task-type in a project context*, never absolutely. If the skill cannot name all three of `task-type + project + FEAT-id`, it must not write the lesson — the evidence is too thin and a categorical claim would mislead future runs.

### 4.3 user-corrections

- **Trigger** — explicit user pushback in the session: «не делай сам», «это неправильно», «переделай», «не лезь в код», «верни как было» — pulled from the session messages source (input #5).
- **Record** — a one-line guard-rail, format `avoid <pattern> — learned from FEAT-NNNN`. Extract the *pattern* of the mistake (e.g. «orchestrator wrote code instead of dispatching»), not the verbatim rebuke.
- **Destination** — §6 of `planner-context.md` (Соглашения именования / lessons).
- **Tone** — descriptive, not accusatory. Capture the pattern, not the wording of the rebuke; the file is read by future sessions and emotional residue distorts decisions.

### 4.4 cost-calibration

- **Trigger** — delta between planned tokens/wall-clock (from `PLANNER_OUTPUT.md` § "Cost estimate") and actual usage exceeds ±30% in either direction.
- **Record** — `estimate adjustment: <task-type> takes ~Nx more/less than planned (FEAT-NNNN)`. Token counts come from session metadata; wall-clock from commit timestamps via `git log`.
- **Destination** — §4 of `planner-context.md` (alongside model notes — costs and model picks are tightly coupled).
- **Tone** — numeric and factual; do not infer cause unless evidence is direct. A 2x overshoot might be model weakness, scope creep, or a flaky test — name only what the evidence supports.

## Always-emit "Lessons learned" section

Every `/plan-reflect` run produces a `## Lessons learned (FEAT-NNNN, YYYY-MM-DD)` block in the chat output, even when nothing new was found. The block has two valid shapes — populated or explicitly empty — and the choice depends only on what the evidence actually supports.

The **empty** case shows exactly this — and only this:

```
## Lessons learned (FEAT-NNNN, YYYY-MM-DD)
_no actionable lessons this session_
```

The **populated** case lists each lesson on its own bullet, tagged with the originating evidence and the destination section, e.g.:

```
## Lessons learned (FEAT-0042, 2026-04-26)
- gap-fill: confirmed missing frontend agent (§1) — evidence: 3 commits routed through general-purpose
- cost-calibration: architecture phase took 1.8x planned tokens (§4) — evidence: session metadata
```

The always-on rule is a deliberate force-function (README §89). The user sees the section and notices when nothing was learned, which prompts a second look — sometimes there *was* a lesson and the skill missed it; sometimes the session was genuinely smooth and the empty block is honest evidence of that. A silent skip would let bad sessions leave no trace and erode trust in the reflection loop over time.

## Output protocol

The skill produces output in a fixed four-step order. Steps run sequentially; do not interleave or reorder.

1. **Write target** — the only file modified is `<project-root>/.claude/planner-context.md`. Use `Write` to create it on first run, or read-modify-write to extend it on subsequent runs. Every new line carries `<!-- learned YYYY-MM-DD from FEAT-NNNN -->` at the end, per README §43; this turns the file into a dated audit log of what the planner has learned about this project, queryable by date or by FEAT-id.
2. **Chat summary** — emit a short bullet list of what changed: which sections were touched, how many lines were added, which evidence sources were used, and which were unavailable. Then render the always-present "Lessons learned" block per the section above. The summary should fit in the user's screen without scrolling — terse beats exhaustive. A typical summary looks like:

   ```
   planner-context.md updated:
   - §1 (agents): +1 row (gap-confirmed)
   - §4 (models): +1 sub-bullet (cost-calibration)
   - evidence used: PLANNER_OUTPUT, git-log, review-files
   - evidence missing: transcripts (cross-session)
   ```

   Then the "Lessons learned" block renders below, completing the summary.
3. **HITL gate for auto-memory** — if the same lesson has been observed in **≥2 distinct sessions** (cross-FEAT), suggest the user create an auto-memory entry. Do **not** create memories autonomously. Phrase the suggestion as a question: «Этот урок встречается во второй раз (FEAT-A, FEAT-B). Создать memory? (требуется явное подтверждение)». The threshold of two is deliberate — single-session lessons are too noisy to promote, and silent auto-creation removes user agency over their global memory.
4. **Stop** — return control to the user or orchestrator. Do not loop, do not chain into `/plan`, do not "improve" the plan post-hoc. Reflection ends when the file is written and the summary is rendered.

## PII / secret stripping

Never copy raw transcript chunks into `planner-context.md`. Extract abstract patterns only — «3 retry iterations to green tests» is fine; «the test `test_user_login_xyz` failed because password = 'p4ssw0rd!'» is not. The file is committed to the project repository and read by every future planning session, so a single leaked secret can propagate widely and is hard to retract once committed.

Before each `Write`, scan the proposed addition and **mask in place** (do not drop the line, do not abort the run) any of the following three categories. Run the scan after lesson extraction and before file write — never trust upstream sources to be clean.

- **Emails** — pattern shaped like `[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}` → replace each match with `<email>`. Keeps the structural fact "an email was here" without exposing the address. Applies to user emails, support addresses, and inline contact strings alike.
- **Long alphanumeric tokens** — any continuous run of 40+ characters from `[A-Za-z0-9_\-]` (API keys, OAuth secrets, JWTs, git SHAs in unusual contexts, password hashes) → replace with `<token>`. The 40-char threshold is deliberately conservative: short identifiers like `FEAT-0001` or `user_id_42` survive untouched, while real-world API tokens (which are nearly always longer than 40 chars) get caught.
- **User-home paths** — `/Users/<name>/...`, `/home/<name>/...`, `C:\\Users\\<name>\\...` → replace the user segment with `<user>` and keep the relative tail intact (e.g. `/Users/alice/projects/foo` becomes `/Users/<user>/projects/foo`). Project structure is signal worth preserving; the operator's username is not.

Masking preserves the lesson while neutralising the leak. Failing closed (refusing to write) is worse than masking — it loses the lesson entirely and discourages running the skill at all, which is exactly the failure mode the reflection loop exists to prevent. If after masking an addition is empty or semantically meaningless (e.g. the entire useful payload was a token), skip that single entry and note in the chat summary that one was dropped due to redaction, so the user knows there was something the skill could not safely record and can decide whether to investigate manually.

## Boundaries

- The **only** writeable target is `<project-root>/.claude/planner-context.md`. No other path may be touched, even with good intent.
- Do **not** modify code under any circumstance — this skill is read-mostly and has no business in source files.
- Do **not** modify `<feature-dir>/PLANNER_OUTPUT.md`. It is a historical record of what was planned at that moment; rewriting it destroys the very evidence this skill depends on for future runs and breaks the audit trail.
- Do **not** invoke other agents or chain into other skills; reflection is a single-pass observation, not an orchestration step.
- Do **not** invent lessons to pad the "Lessons learned" section. Emptiness is a valid, honest result and is preferable to fabricated insight.
- Do **not** rewrite or "tidy up" entries authored by the user manually in `planner-context.md`. Manual edits are sources of truth; only append new lines, never overwrite.

The boundaries above are deliberately strict because the value of `planner-context.md` lies in its trustworthiness. A reflection skill that quietly edits unrelated files, fabricates lessons to look productive, or rewrites historical artifacts is worse than no skill at all — it teaches the user not to trust the loop.

## Reference index

This skill has no references. The workflow is small and self-contained — five inputs, four update types, one writeable target, one always-emit section, one HITL gate. Loading it should not pull additional files; the entire procedure fits in this single document and benefits from being read top-to-bottom in one pass.

If a future change pushes content past the 170-line budget, the spec (PLAN-01 §6) calls for splitting into references at that point. Until then, inline beats progressive disclosure for a skill this focused — every fact is on the page when the skill activates, no second hop required, no risk of partial loading. The cost is one full read each time the skill runs; the benefit is zero ambiguity about where a rule lives.