From 0a45fcbdfd09599ac000de9a7961b8d5e90258dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Tue, 19 May 2026 06:23:00 +0300 Subject: [PATCH] =?UTF-8?q?feat(skills):=20/brain-retro=20=E2=80=94=20obse?= =?UTF-8?q?rver=20evidence=20aggregator?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Read-only skill at .claude/skills/brain-retro/. Aggregates JSONL evidence + optional notes for owner review. Side-effect: bumps docs/observer/.read-counter.json (used by C3 observer-of-observer 54-week self-prune). Includes Factor analysis matrix (v1.1+ amendment): 5 axes (triggers_matched / candidates_dropped_because / boundaries_applied / hard_floor.rules / task_classification) + cross-tab factor×factor. Never auto-edits normative files. Per Pravila §16.2 + ADR-011 + spec v1.1 §5.5. +cspell словарь «разруливают», «брейн». Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/skills/brain-retro/SKILL.md | 40 ++++++ .../references/aggregation-template.md | 115 ++++++++++++++++++ cspell-words.txt | 2 + 3 files changed, 157 insertions(+) create mode 100644 .claude/skills/brain-retro/SKILL.md create mode 100644 .claude/skills/brain-retro/references/aggregation-template.md diff --git a/.claude/skills/brain-retro/SKILL.md b/.claude/skills/brain-retro/SKILL.md new file mode 100644 index 00000000..0ddeed1b --- /dev/null +++ b/.claude/skills/brain-retro/SKILL.md @@ -0,0 +1,40 @@ +--- +name: brain-retro +description: Use ONCE PER SPRINT (or by explicit user invocation "брейн-ретро") to aggregate evidence from docs/observer/episodes-*.jsonl + notes/*.md and propose regulatory candidates. Read-only — never edits Tooling/Pravila/PSR_v1 automatically; only proposes. +--- + +# Brain Retro + +Aggregator over observer evidence. Reads JSONL + optional MD notes, surfaces candidates for normative updates. User decides what to apply. + +## When to invoke + +- Explicit user request: «брейн-ретро» / «сделай brain-retro» / `/brain-retro`. +- Periodic — owner discretion (e.g. end of sprint). +- NOT auto-invoked. + +## What it does NOT do + +- Does NOT edit `docs/Tooling_v8_3.md`, `docs/Pravila_raboty_Claude_v1_1.md`, `docs/Plugin_stack_rules_v1.md`, `CLAUDE.md`, or any normative file. +- Does NOT write to `docs/observer/episodes-*.jsonl` (read-only). +- Does NOT trigger automatic memory updates. + +## Procedure + +1. **Determine period**: ask user «за какой период» or default to «since last brain-retro» (find latest `docs/observer/notes/YYYY-MM-DD-brain-retro-*.md`). +2. **Read evidence**: glob `docs/observer/episodes-YYYY-MM.jsonl` for the period; read all lines as JSON. +3. **Read optional notes**: glob `docs/observer/notes/*.md` filtered by date. +4. **Update read-counter**: bump `docs/observer/.read-counter.json` `last_read_at` to now, increment `read_count_last_period`. (Side-effect — used by C3 observer-of-observer.) +5. **Aggregate** per `references/aggregation-template.md` — includes Factor analysis matrix (v1.1+) on 5 axes. +6. **Propose candidates** — clearly separated section «Candidates for owner review». Each candidate has rationale + suggested edit + rejection-option. +7. **Save retro note**: `docs/observer/notes/YYYY-MM-DD-brain-retro.md` with full aggregation. +8. **Report to user**: high-signal summary. + +## Output anatomy + +See `references/aggregation-template.md`. + +## Behavioral rule reminders + +- **«Не использован ≠ проблема»** — when reporting node usage counts, NEVER mark unused nodes as «zombie» / «removal candidate». Cite `memory/feedback_brain_unused_tools_not_problem.md`. +- **No auto-edit** — every regulatory suggestion is a candidate, not an action. diff --git a/.claude/skills/brain-retro/references/aggregation-template.md b/.claude/skills/brain-retro/references/aggregation-template.md new file mode 100644 index 00000000..355f0d0f --- /dev/null +++ b/.claude/skills/brain-retro/references/aggregation-template.md @@ -0,0 +1,115 @@ +# Brain-retro aggregation template + +## Period + +YYYY-MM-DD .. YYYY-MM-DD ({N} sessions) + +## Path-type distribution + +| path_type | count | % | +|---|---|---| +| regulated | A | x% | +| improvised | B | y% | +| alternative | C | z% | +| mixed | D | w% | + +## Outcome distribution + +| outcome | count | +|---|---| +| success | M | +| partial | N | +| failure | O | +| aborted | P | + +## Top nodes used (from `skill_invoked` events) + +| node | times used | first / last | +|---|---|---| + +## Factor analysis matrix (v1.1+ — from `routing_decision` events + `primary_rationale`) + +Per-node breakdown by 5 factor axes (per spec §5.2.1). + +### Axis 1: triggers_matched → node + +«Какие триггеры чаще всего ведут к этому узлу» + +| node | trigger | count | +|---|---|---| + +### Axis 2: candidates_considered.dropped_because → node + +«Какие альтернативы и почему отбрасываются в пользу этого узла» + +| node | dropped alternative | dropped_because (top reason) | count | +|---|---|---|---| + +### Axis 3: boundaries_applied → node + +«Какие ADR / R-rules чаще всего разруливают в пользу этого узла» + +| node | boundary (ADR-NNN / PSR R-rule) | count | +|---|---|---| + +### Axis 4: hard_floor.rules → invoked frequency + +«Как часто узел вынуждается hard-floor §12/§14/§15» + +| node | rule | invoked-count | total decisions | % forced | +|---|---|---|---|---| + +### Axis 5: task_classification → node + +«В каких классах задач узел доминирует» + +| task_classification | top node | secondary nodes | +|---|---|---| + +### Cross-tab: factor × factor + +Pairs of factors that co-occur to resolve specific conflicts (e.g. «ADR-009 ↔ triggers_matched=['discovery']» — 8 раз). + +| factor pair | combined count | interpretation | +|---|---|---| + +## Canonical chains L1–L12 hit rate + +| chain | times | notes | +|---|---|---| + +## Improvised chains (path_type=improvised, repeated ≥2) + +| node-set | times | candidate L13+? | +|---|---|---| + +## chain_divergence cases + +| canonical | chosen | reason | recurring? | +|---|---|---|---| + +## Top error classes + +| error class | count | recovery pattern | +|---|---|---| + +## confusion_marker hot-spots + +| context | count | +|---|---| + +## Candidates for owner review + +### Candidate 1: `` + +- **Type**: new canonical chain L13+ / new ADR / boundary clarification / etc. +- **Evidence**: refs to JSONL lines (file:line). +- **Suggested action**: `<concrete edit>`. +- **Cost / risk**: `<brief>`. + +(repeat for each candidate; could be 0) + +## Informational metrics (NOT alerts) + +- Nodes used at least once this period: K / 60+ +- Nodes never used since beginning of observer logs: L / 60+ — **not a problem** per [feedback_brain_unused_tools_not_problem](../../../memory/feedback_brain_unused_tools_not_problem.md) diff --git a/cspell-words.txt b/cspell-words.txt index 5b2d183e..c0593965 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1463,4 +1463,6 @@ CCS версионный стейлнес апдейты +разруливают +брейн нодов