\r \r

Reflect — Learn + Retro + Write Skill\r

\r Three modes: capture learnings (default), weekly retrospective, or codify recurring patterns into skills.\r \r Rule labels: [IRON LAW] means a non-negotiable correctness constraint. [GUIDANCE] means a strong default that may adapt when context justifies it.\r \r

Mode Selection\r

\r

• Learn (default): "what have we learned", "add learning", "show learnings", "prune learnings"\r
• Retro: "weekly retro", "what did we ship", "retrospective", or --retro flag\r
• Write Skill: "write a skill", "create a skill", "codify this pattern", "edit this skill"\r \r ---\r \r

Learn Mode\r

\r Capture only what the user explicitly wants to preserve so future sessions can reuse it.\r \r

Invocation Rule\r

\r [IRON LAW] /taku-reflect is manual. Do not create or update long-term learnings unless the user explicitly invokes reflect.\r \r

Storage\r

\r Learnings live in .taku/learnings/{project-slug}.jsonl. Each line:\r \r

{"id":"L2026-04-21-001","timestamp":"2026-04-21T12:00:00Z","type":"preference/high","context":"Multi-file repository change","learning":"User prefers plan-first before non-trivial edits","action":"Start with code reading and short execution plan","apply_when":{"task_types":["feature","refactor","bugfix"],"keywords":["multi-file","plan","design"]},"status":"active"}\r
```\r
\r
### Types\r
\r
Each type includes a confidence suffix: `/high`, `/medium`, or `/low`.\r
\r
- **pattern** — A reusable approach that worked well\r
- **pitfall** — A mistake to avoid\r
- **preference** — A user-stated preference or convention\r
- **discovery** — A non-obvious insight about the codebase\r
\r
Confidence meanings: **high** — verified by testing or user confirmation. **medium** — observed pattern, likely correct. **low** — hypothesis, needs validation.\r
\r
### Required Fields\r
\r
**Auto-generated** (no user confirmation needed):\r
- `id` — Stable identifier, auto-generated as `L{date}-{seq}`\r
- `timestamp` — ISO8601 UTC, auto-generated\r
- `status` — Defaults to `active`; only changes during PRUNE\r
\r
**User confirms:**\r
- `type` — `pattern|pitfall|preference|discovery` with `/confidence` suffix (e.g., `pattern/high`, `pitfall/medium`)\r
- `context` — What work this came from\r
- `learning` — The reusable takeaway\r
- `action` — What future sessions should do\r
- `apply_when` — Task types and keywords for later recall (`task_types` + `keywords`)\r
\r
### Script-Backed Operations\r
\r
Use `scripts/learnings.py` for all learnings file operations. Do not hand-edit `.taku/learnings/*.jsonl` unless the script is unavailable and the user explicitly approves a fallback.\r
\r
**ADD:** Gather `type` (with confidence suffix), `context`, `learning`, `action`, and minimal `apply_when` values. Append only after the user confirms the learning should be kept.\r
\r
```bash\r
python3 \x3Cpath-to-this-skill>/scripts/learnings.py add --project-root . --type preference/high --context "..." --learning "..." --action "..." --task-types feature,refactor --keywords plan,design\r
```\r
\r
**SEARCH:** Query existing learnings through the script and present matches grouped by type when useful.\r
\r
```bash\r
python3 \x3Cpath-to-this-skill>/scripts/learnings.py search --project-root . --query "plan" --task-type feature --keywords plan,design\r
```\r
\r
**PRUNE:** Use the script to list stale or low-confidence candidates. Present each flagged entry: Remove / Keep / Update. Do not delete automatically.\r
\r
```bash\r
python3 \x3Cpath-to-this-skill>/scripts/learnings.py prune --project-root . --days 30\r
```\r
\r
**EXPORT:** Convert to markdown through the script. Offer to append exported content to `AGENTS.md` or `CLAUDE.md` only when the user confirms an upgrade.\r
\r
```bash\r
python3 \x3Cpath-to-this-skill>/scripts/learnings.py export --project-root .\r
```\r
\r
**Why JSONL over markdown:** JSONL entries can be searched with grep, parsed programmatically, and deduplicated. Markdown learnings files become unstructured text that's hard to query or prune.\r
\r
### Auto-Recall\r
\r
Other Taku phases may search existing learnings automatically, but only as context:\r
\r
- Search with `scripts/learnings.py search` after task classification and before PLAN, BUILD, REVIEW, and VERIFY\r
- Filter by task type and simple keyword overlap\r
- Prefer `high` confidence, then `medium`\r
- Show at most 3-5 relevant learnings\r
\r
This recall must never create, edit, or prune learnings. Long-term memory changes happen only inside `/taku-reflect`.\r
\r
### Project Bootstrap\r
\r
On the first successful reflect run for a project, check whether the project-level instruction files advertise the optional Taku learnings protocol.\r
\r
**When to check:**\r
\r
- `.taku/` already exists or this reflect run is about to create `.taku/learnings/{project-slug}.jsonl`\r
- Run `python3 \x3Cpath-to-this-skill>/scripts/learnings.py bootstrap-check --project-root .`\r
- Treat the result as a suggestion only\r
\r
**Target selection:**\r
\r
- If only `AGENTS.md` exists, suggest installing the protocol there\r
- If only `CLAUDE.md` exists, suggest installing the protocol there\r
- If both files exist, suggest installing the same protocol block into both files so non-Taku sessions do not depend on which project instruction file gets loaded\r
- If one file already has the block and the other does not, suggest installing only the missing file\r
- If neither file exists, do not create one automatically; note that no project-level bootstrap target exists yet\r
\r
**Protocol block:** The script owns this exact block.\r
\r
```md\r
\x3C!-- TAKU_LEARNINGS_PROTOCOL:START -->\r
## Taku Learnings\r
\r
If `.taku/learnings/{project-slug}.jsonl` exists, consult it before non-trivial planning, implementation, review, or debugging. Treat matching entries as context, not hard rules.\r
\r
Do not create, edit, or prune learnings unless the user explicitly invokes `/taku-reflect`. Only stable repeated preferences should be promoted into project-level instructions.\r
\x3C!-- TAKU_LEARNINGS_PROTOCOL:END -->\r
```\r
\r
**Rules:**\r
\r
- This is a bootstrap protocol, not a promotion of specific learnings\r
- The JSONL file is the canonical source; `AGENTS.md` and `CLAUDE.md` are optional discovery layers\r
- Detect existing installation by the `TAKU_LEARNINGS_PROTOCOL` markers\r
- Never install automatically. Show a `Project Bootstrap Suggestion`; if the user explicitly says to install it, run:\r
\r
```bash\r
python3 \x3Cpath-to-this-skill>/scripts/learnings.py bootstrap-install --project-root . --targets AGENTS.md,CLAUDE.md\r
```\r
\r
### Output Format\r
\r
When running learn mode, organize results as:\r
\r
- **Recorded** — learnings added or updated in this reflect run\r
- **Relevant Existing Learnings** — prior entries relevant to the current work\r
- **Promotion Suggestions** — suggestions only; do not upgrade anything automatically\r
- **Project Bootstrap Suggestion** — suggest installing the Taku learnings protocol in `AGENTS.md` and/or `CLAUDE.md` when the project has not been bootstrapped yet\r
\r
---\r
\r
## Retro Mode\r
\r
Analyze what the team shipped, how the work happened, and where to improve. Evidence-based, specific, candid.\r
\r
Use `references/retro-report.md` as the local report scaffold; fill it with evidence from the steps below and remove placeholders.\r
\r
### Arguments\r
\r
- `/taku-reflect` — learn mode (default)\r
- `/taku-reflect --retro` — last 7 days\r
- `/taku-reflect --retro 14d` — last 14 days\r
- `/taku-reflect --retro 30d` — last 30 days\r
\r
### Step 1: Gather Raw Data\r
\r
```bash\r
git config user.name && git config user.email\r
git log origin/\x3Cbase> --since="\x3Cwindow>" --format="%H|%aN|%ae|%ai|%s" --shortstat\r
git log origin/\x3Cbase> --since="\x3Cwindow>" --format="COMMIT:%H|%aN" --numstat\r
git log origin/\x3Cbase> --since="\x3Cwindow>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn\r
git shortlog origin/\x3Cbase> --since="\x3Cwindow>" -sn --no-merges\r
```\r
\r
### Step 2: Compute Metrics\r
\r
Summary: commits, contributors, PRs, insertions, deletions, net LOC, test LOC ratio, active days, sessions, avg LOC/session-hr. Per-author leaderboard sorted by commits.\r
\r
### Step 3: Time & Session Patterns\r
\r
Hourly histogram. Detect sessions (45-min gap). Classify: Deep (50+ min), Medium (20-50), Micro (\x3C20).\r
\r
### Step 4: Work Patterns\r
\r
Commit type breakdown by conventional prefix. Flag fix ratio > 50%. Hotspot analysis: top 10 files. Flag files changed 5+ times.\r
\r
### Step 5: Team Member Analysis\r
\r
For each contributor: commits, LOC, test ratio, areas, biggest ship.\r
**Praise** (anchored in commits): 1-2 things. **Growth area** (framed as investment): 1 thing.\r
\r
### Step 6: Week-over-Week Trends\r
\r
Load prior retro from `.taku/retros/`. Compare key metrics.\r
\r
### Step 7: Narrative\r
\r
Output: Summary table + trends, Time & sessions, Your week + team, Top 3 Wins + 3 Improvements + 3 Habits.\r
\r
### Step 8: Save\r
\r
Save to `.taku/retros/{date}.md`. Append trends to `.taku/retros/trends.jsonl`.\r
\r
---\r
\r
## Write Skill Mode\r
\r
Codify recurring patterns into reusable skills, but only after the user confirms they want to write one.\r
\r
Full process in `references/writing-skills.md`. Load it and follow the instructions. That reference is substantial (~200 lines) with its own anti-rationalization table and known pitfalls — it functions as a self-contained skill within the reflect directory, not a lightweight helper.\r
\r
Quick summary:\r
- Choose skill type: TECHNIQUE (concrete method), PATTERN (mental model), REFERENCE (lookup table)\r
- Follow RED-GREEN-REFACTOR: baseline test → write minimal skill → close loopholes\r
- Keep under 500 lines; split to `references/` if needed\r
- Description field: triggering conditions only, never summarize workflow\r
\r
### Promotion Paths\r
\r
Keep upgrades narrow. Only suggest these two:\r
\r
1. **Project-level constraint candidate**\r
   - Condition: `type=preference/high`, repeated or confirmed 2+ times\r
   - Suggestion: propose upgrading the preference into `AGENTS.md` if present, otherwise `CLAUDE.md`\r
   - Rule: never write the file automatically; ask the user first\r
\r
2. **Write Skill candidate**\r
   - Condition: the same pattern, pitfall, or decision method recurs across 2-3 sprints\r
   - Suggestion: `This pattern keeps recurring. Suggest codifying it as a skill.`\r
   - Rule: ask the user whether to proceed before loading `references/writing-skills.md`\r
\r
Bootstrap is separate from promotion. Installing the Taku learnings protocol in `AGENTS.md` or `CLAUDE.md` only makes the knowledge base discoverable; it must not be used to smuggle concrete learnings past the promotion rules above.\r
\r
---\r
\r
## Anti-Rationalization\r
\r
| Excuse | Why it's wrong |\r
|--------|---------------|\r
| "I'll remember this" | You won't. Next session starts fresh. Write it down. |\r
| "This is too obvious to log" | Obvious now. Not obvious in 3 weeks after 50 other sessions. |\r
| "We didn't do much this week" | Even small weeks have patterns worth examining. |\r
| "Retros waste time" | 5 minutes of reflection saves hours of repeated mistakes. |\r
\r
## Known Pitfalls\r
\r
**Learnings file becomes a dumping ground.** Over 30 sessions, 200+ entries. Most trivial. Signal buried in noise.\r
\r
*Prevention:* Use PRUNE regularly. Every 30 days, remove trivial observations, update stale patterns, delete low-confidence entries. 30 high-quality insights > 200 entries of noise.\r
\r
**Retro becomes a vanity metric exercise.** "142 commits, 8,400 lines." But 6,000 were generated code and 40 were auto-bumps.\r
\r
*Prevention:* Step 4 computes commit type breakdown and flags fix ratio. Note when metrics are inflated. Value is in analysis, not numbers.\r
\r
**Saving learnings but never searching them.** 50 learnings recorded, none referenced. Team repeated the same mistake 3 times.\r
\r
*Prevention:* Auto-search relevant learnings in later phases as context. Query the knowledge base, don't just write to it.\r
\r
**Auto-upgrading without consent.** A repeated preference was detected and silently written into a project rule file. The user disagreed with the wording and had to undo it.\r
\r
*Prevention:* Promotion Suggestions are suggestions only. Upgrades to `AGENTS.md`, `CLAUDE.md`, or a new skill always require explicit user confirmation first.\r
\r
**Bootstrap drift between `AGENTS.md` and `CLAUDE.md`.** One file mentioned `.taku/learnings` and the other did not. Different agents got different behavior depending on which instruction file they loaded.\r
\r
*Prevention:* When both files exist, suggest injecting the exact same `TAKU_LEARNINGS_PROTOCOL` block into both. If only one file is missing the block later, patch only the missing file instead of rewriting both.\r