kaizen
Skill12 starsChanged 14 days agoMITView on GitHub
Trigger: kaizen, retrospective, continuous improvement, mejora continua, /akili-archive Kaizen step, apply pending kaizen standardizations, kaizen apply, aplicar estandarizaciones kaizen. Run the bounded two-phase Kaizen loop: Measure → Learn → Standardize → Record on any branch, then apply the pending backlog on the apply-capable branch.
20 other projects use a version of this.
Adopted by
Most recently taken up by
- AtilaMedeiros/skillstheir own version, first seen Nov 16, 2026
- Ivan-propio/claude-skillstheir own version, first seen Nov 16, 2026
- viniciusamelio/skillstheir own version, first seen Nov 8, 2026
- LuisSambrano/antigravity-configtheir own version, first seen Nov 8, 2026
- spenserhale/skillstheir own version, first seen Nov 1, 2026
- allanninal/claude-code-skillstheir own version, first seen Oct 17, 2026
Other versions20 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 20
- kuya-egg/Monozukuri★ 11same name
- xfstudio/skills★ 9same name
- flpbalada/fb-skills★ 8same name
- LuisSambrano/antigravity-config★ 8same name
- hfadhlullah/kaizen★ 6same name
- freskhu/genesis★ 5same name
- JoeCotellese/claude-code-config★ 5same name
- nek1987/auto-agent-harness★ 4same name
- ai4brands-design/claude-skills★ 2same name
- allanninal/claude-code-skills★ 1same name
10 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository35 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/skills/react-doctor/AGENTS.mdAGENTS.md
- .claude/skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ai-agent-developmentSkill
- angular-developerSkill
- api-design-principlesSkill
- aws-serverlessSkill
- brainstormingSkill
- cavemanSkill
- cognitive-doc-designSkill
- diagram-designSkill
- error-handling-patternsSkill
- frontend-designSkill
- golang-proSkill
- gsap-animationSkill
- impeccable-bridgeSkill
- impeccableSkill
- judgment-daySkill
- nestjs-expertSkill
- product-manager-toolkitSkill
- pr-reviewSkill
- react-doctorSkill
- security-auditSkill
- seo-auditSkill
- shadcn-uiSkill
- social-marketingSkill
- software-architectSkill
- stitch-designSkill
- systematic-debuggingSkill
- tailwind-design-systemSkill
- tddSkill
- ui-ux-pro-maxSkill
- vercel-react-best-practicesSkill
- video-productionSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 2 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 55
Run the four phases in order.
- Very specific: line 84
Every lesson names a root cause (apply 5W1H) and cites its evidence — file + section, e.g.
- Distinctive: line 86
Prefer zero lessons over filler.
- Very specific: line 128
Write the retrospective to docs/specs/kaizen/<safe-spec-slug>.md — one file per spec, outside the spec folder so it survives archiving:
- Very specific: line 132
Create docs/specs/kaizen/ if it does not exist.
- Very specific: line 133
Never prepend to ## Entries and never touch ## Active Lessons in docs/specs/kaizen-log.md — the apply phase on the apply-capable branch is …
- Very specific: line 258
Keep the table at 10 rows or fewer.
- Very specific: line 259
If docs/specs/kaizen-log.md does not exist, create it with the header and the digest section only, on the apply-capable branch.
- Very specific: line 260
If it still carries a populated legacy ## Entries section without the freeze note, add the freeze note (below) on this first apply pass.
- Distinctive: line 299
Every write decision in this skill turns on one question: which branch, if any, is apply-capable right now?
- Very specific: line 308
No fallback of any kind exists for step 5: no branch-name heuristic (develop, staging, …), no ref lookup, no merge-history inference.
“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Kaizen — The AKILI Continuous-Improvement Skill
Kaizen (改善, kai = change, zen = better) is the Japanese philosophy of continuous improvement through small, disciplined, daily steps. This skill turns that philosophy into an executable retrospective for AI-assisted development: every archived spec must leave the project — and the methodology itself — slightly better than it found them.
Other methodologies execute specs. AKILI learns from every spec.
Activation Contract
Load this skill when:
/akili-archivereaches its Kaizen Retrospective step (the primary, automatic trigger),- the user explicitly requests a kaizen retrospective / continuous-improvement pass over a spec or project, or
- Apply Mode — the user asks to apply pending kaizen standardizations ("kaizen apply", "aplicar estandarizaciones kaizen"), or
/akili-archivefinishes a retrospective with the apply-capable branch checked out and offers the pending backlog.
The loop runs in two phases with two different homes:
| Phase | Runs where | Writes |
| Retrospective (Measure → Learn → Standardize → Record) | any branch | the spec's own entry file under docs/specs/kaizen/ |
| Apply (the pending backlog) | runs only on the apply-capable branch (Branch Context) | HITL-approved shared files, the digest, and status flips in entry files |
Apply Mode is standalone: no spec argument, no active archive — it works over the whole pending backlog, so it stays reachable long after the specs that produced it were archived. Invoked anywhere else, it declines in one line naming the apply-capable branch — its pinned name when the Integration Branch: pin exists, otherwise the resolved default branch ("Apply Mode runs only on <apply-capable branch> — see Branch Context; the pending backlog stays recorded and is re-offered there") — and does nothing else. No separate kaizen command exists; this is an activation of this skill.
The retrospective is bounded: one pass, at most 3 lessons, one entry file. It must never block the archive or any other command that invoked it.
Philosophy → Engineering Mapping
Each Kaizen concept maps to a concrete AKILI mechanism. Use this vocabulary in reports so the improvement culture stays visible.
| Concept | Meaning | In AKILI |
| Kai + Zen | Small changes that make things better, every day, forever | Every /akili-archive is an improvement opportunity; the loop never "finishes" |
| Small steps (Maurer) | Improvements so small they cannot fail or trigger resistance | Standardization edits are 1–3 lines; never rewrite a document to institutionalize a lesson |
| Small questions (Maurer) | Gentle questions unlock root causes better than big alarming ones | Learn step asks: "What is the smallest rule that would have prevented this rework?" |
| PDCA (Deming) | Plan → Do → Check → Act | Plan = the spec; Do = execute/test; Check = validate + Measure; Act = Standardize. The retrospective closes the cycle the pipeline opened |
| MUDA | Waste: any activity that adds no value | Rework attempts (defects), pivots (planning waste), token waste (oversized context, re-reading), stale docs (drift = inventory waste), quick-escalations (misrouted work). Measure = hunt MUDA |
| Jidoka | Stop the line the moment a defect appears | AKILI already practices it: the Tester keeps a test red on PRODUCT_BUG; the harness HALTs on FATAL_FAIL. Name it in reports — the methodology owns this concept |
| Gemba / 3 GEN | Real place, real thing, real facts — never speculate | Every lesson must cite evidence from the actual artifacts (execution.md, test-report.md, validation-report.md); use 5W1H to reach root cause |
| LUP (one-point lesson) | One lesson, one page, instantly teachable | The ## Active Lessons digest row: one lesson, one line, one owner document |
| Standardize & repeat | A fix becomes a standard, then the next improvement begins | Applied lessons live in constitution guides/templates; the digest retires them once institutionalized |
The Loop Contract
Run the four phases in order. Beyond the artifacts the invoking command already loaded, read only the kaizen inputs these phases name: the drift report (phase 1), the digest and the entry files under docs/specs/kaizen/ (phase 2).
1. Measure
Extract improvement signals from the spec's own evidence:
| Signal | Source |
| Reviewer FAIL rework attempts, HALTs, FATAL_FAILs | execution.md task entries |
| Pivots | execution.md ## Pivot Record blocks |
| PRODUCT_BUG findings | test-report.md |
| Severe judgment-day findings | design.md / specify review notes, if recorded |
| Validation FAIL / WARN counts | validation-report.md |
Escalations from /akili-quick into this spec | docs/specs/quick/quick-log.md, if applicable |
| Drift attributable to this spec | the most recent drift-*.md report in docs/specs/audits/, legacy docs/specs/drift-report.md as fallback |
Tasks closed under REVIEW_WAIVED (by flag) | execution.md ## REVIEW_WAIVED blocks — inline / same-model = no exercised gate; degraded-pair = exercised, noted |
Tasks closed under REVIEW_SKIPPED (by task) | execution.md ## REVIEW_SKIPPED blocks — each task's predicate evidence (Review intensity, Step 2.3) |
| Escaped defects (§3) | a defect found after a task closed — at /akili-test, /akili-validate, a later task, the closure gate, or HITL — in a task carrying a REVIEW_SKIPPED record: test-report.md, validation-report.md, execution.md (later tasks), closure gate output, HITL notes |
Most recent report means the highest Date header inside the drift-*.md files (a security-*.md index is not a drift report), ties broken by the newest filename in lexical order — never filesystem mtime, which a checkout destroys. A scaffolded README.md or .gitkeep is not a report: fall back to legacy docs/specs/drift-report.md only when the directory holds no drift-*.md file. Both reads are optional — a missing drift source is a blank row, not a blocker.
If every signal is clean (zero rework, no pivots, no product bugs, no severe findings, no REVIEW_WAIVED waiver flagged inline or same-model, and no escaped defect in any task carrying a REVIEW_SKIPPED record), write a one-line clean run entry file in phase 4 and skip phases 2–3. A clean spec teaches nothing new — say so. A REVIEW_SKIPPED record with no escaped defect against it is routine and does not by itself break the clean read; an escaped defect against one does.
2. Learn
First load the recurrence inputs: the ## Active Lessons digest and every entry file under docs/specs/kaizen/, including their ## Noted, not a lesson sections. Sub-threshold signals now accumulate in entry files across branches; the digest alone no longer sees them.
Then distill 0 to 3 lessons. Hard rules:
- Every lesson names a root cause (apply 5W1H) and cites its evidence — file + section, e.g.
execution.md — Task 4, attempts 1–2 (Violated Rule: design.md#tokens). Gemba: real facts only. - Generic lessons are banned ("write better tests", "be more careful"). A lesson must change what a future command concretely does.
- Prefer zero lessons over filler.
- Sub-threshold signals that are not yet lessons go under
## Noted, not a lessonin the entry file — that section is the recurrence feed for later retrospectives. - If the same root cause already exists — in the digest or in another entry file, under either ID grammar (legacy
KZ-###orKZ-<safe-spec-slug>-<n>) — do not duplicate it. Record adigest-updatepending item instead:Target= thatKZ-id,Severity= the raised severity,Edit= the digest change (this spec added as a source, plus the recurrence note). A repeat is a strong standardization signal, but it is a digest mutation, so it is recorded here and merged at apply time — never written live to the digest from any branch. - Classify each lesson's target:
- Product (default): the root cause lives in this project — its guides, templates, design tokens, or personas.
- Methodology: the root cause is AKILI itself — an ambiguous command step, a template gap, a missing skill. These lessons make the methodology learn from every tool built with it.
- Product + Methodology (dual): the lesson fixes this project and names nothing project-specific — no stack, domain, or local convention (a universal persona rule is the standing example). A generalizable lesson is a template gap in disguise: propose the local edit and the upstream. The local edit is applied or recorded pending according to Branch Context (phase 3); the upstream recommendation is recorded as a
Kind: upstreampending item in the entry file either way.
3. Standardize (branch-gated HITL)
For each lesson, propose exactly one minimal edit (1–3 lines) targeting the most durable home:
- root
CLAUDE.md/AGENTS.md(or a child module guide) — behavioral rules docs/specs/general-setup/templates — spec-authoring rulesdocs/ux-ui/design.md— missing tokens or visual rules.agents/personas — harness-role rules (append-only, never rewrite)- Methodology lessons: no local edit — record a
Kind: upstreampending item (Target: methodology,Edit= the proposed upstream text) in the entry file, on any branch. The proposal is still presented to the user; it is collected into one upstream report at the next apply pass (see Apply Mode). - Dual (Product + Methodology) lessons: both, not either — the local edit follows the branch gate below, and the upstream half is recorded as its own
Kind: upstreampending item, independent of how the local edit resolves.
Assign a severity: High = caused a HALT, pivot, or PRODUCT_BUG; Medium = caused rework or a severe finding; Low = friction only.
Then resolve Branch Context (Hard Rules). It decides whether each proposed edit is written or recorded:
| Branch Context | What Standardize does |
| Spec branch (or unresolved) | Record every proposed edit as a pending item (Kind: standardization, Status: pending) with its exact target and verbatim text. Present the lessons and their proposed edits to the user anyway — the gate moves the write, not the review — and say in one line that they await the apply phase on the apply-capable branch. No HITL apply menu fires. No shared file is edited: not a persona, guide, template, design doc, TRD, or the digest. |
Default branch, while an Integration Branch: pin exists | The same as a spec branch: record every proposed edit as a pending item and present it to the user anyway. No HITL menu fires here — the default branch is not the writer while the pin stands — and the one-line note names the pinned integration branch instead of saying "the default branch". |
| Apply-capable branch (the pinned integration branch when the pin exists, otherwise the default branch) | Run the HITL menu below and apply approved edits in this pass (solo fast path — today's behavior), then stamp each item's Status in the entry file. |
The menu, on the apply-capable branch:
- Apply all — make every proposed edit in this pass
- Apply selected — user picks by lesson ID
- Defer all — record the proposals as
deferred; they stay in the backlog and are re-offered at every later apply pass - Type something — adjust a proposal before applying
Recommend option 1 when any High-severity lesson exists, otherwise option 3. Writing the entry file is automatic; every edit outside the entry file requires this approval — and on a spec branch, or on the default branch while an integration pin exists, no such edit happens at all, approved or not.
Standardize decides; Record writes. On a spec branch — or on the default branch while an integration pin exists — the pending items are composed here and land in the entry file in phase 4; on the apply-capable branch the edits are applied here and their resulting statuses are stamped into the same entry file in phase 4 — one write, not two.
4. Record
Write the retrospective to docs/specs/kaizen/<safe-spec-slug>.md — one file per spec, outside the spec folder so it survives archiving:
- Derive the filename from the spec path with the archive's
$SAFE_NAMErule (/→--):changes/feature-a→changes--feature-a.md. No date prefix — the date lives in the entry's Document Control. - Re-run detection is an exact-name existence check on that path — never a glob. If the file exists (the archive was re-run for the same spec), update it in place; never create a second file for the same spec.
- Create
docs/specs/kaizen/if it does not exist. In a legacy project this is the only structural change the retrospective makes. - Never prepend to
## Entriesand never touch## Active Lessonsindocs/specs/kaizen-log.md— the apply phase on the apply-capable branch is the digest's single writer, and the legacy entries are frozen.
The entry file
# Kaizen Entry — changes/feature-a
## Document Control
| Field | Value |
|---|---|
| Spec Path | `changes/feature-a` |
| Date | 2026-08-21 |
| Branch | feat-a |
| Archive Run | 1 |
| Approval Mode | gated |
## Metrics
| Signal | Value | Source |
|---|---|---|
| Tasks executed | 8 | tasks.md |
| Reviewer FAIL rework attempts | 3 (Task 4 x2, Task 7 x1) | execution.md |
| HALTs / FATAL_FAILs | 0 | execution.md |
| Pivots | 1 (Task 5 — storage approach) | execution.md — ## Pivot Record: Task 5 |
| PRODUCT_BUGs | 1 (resolved) | test-report.md |
| Judgment-day severe findings | 2 | design.md review notes |
| Validation FAIL / WARN | 0 / 2 | validation-report.md |
| Tasks closed under `REVIEW_WAIVED` (by flag) | 0 | execution.md |
| Tasks closed under `REVIEW_SKIPPED` (by task) | 0 | execution.md |
| Escaped defects (§3) | 0 | test-report.md / validation-report.md |
## Lessons
- **KZ-changes--feature-a-1 — Empty-state tokens were missing from the design phase.** (Product, Medium)
- Root cause: `design.md` specified list components without empty-state tokens, so the
Implementer improvised styles and the Reviewer failed Task 4 twice on token compliance.
- Evidence: execution.md — Task 4, attempts 1–2 (Violated Rule: design.md#tokens).
- Standardization: → P1
## Noted, not a lesson
- Two validation WARNs on copy tone — below the lesson bar; feeds the recurrence check.
## Pending Items
### P1
| Field | Value |
|---|---|
| Kind | standardization |
| Target | `docs/specs/general-setup/design.md` |
| Edit | Add an empty-state token check to the Design Impact checklist. |
| Severity | Medium |
| Status | pending |A clean run keeps the same shape with the Metrics table and a one-line statement in place of ## Lessons.
Lesson IDs are KZ-<safe-spec-slug>-<n> — the same $SAFE_NAME slug as the filename, so the ID is legal in the digest's ID column and in inline citations. The global KZ-### counter is retired for new lessons; existing KZ-### IDs are never renumbered and stay valid targets for recurrence.
Kind values — one schema covers every write a spec branch defers:
| Kind | Origin |
standardization | A lesson's proposed edit (phase 3) |
digest-update | A recurrence of an existing lesson (phase 2) — Target is the KZ-id, not a file |
guide-sync | /akili-archive's agent-guide sync, deferred from a spec branch |
factual-sweep | /akili-archive's factual-claims sweep, deferred from a spec branch |
trd-adr | /akili-archive's TRD & ADR sync — the superseding decision text, carrying no ADR number (numbers are allocated at apply time) |
upstream | A Methodology lesson's proposed edit to the AKILI methodology repository, or the upstream half of a dual lesson. Target is the literal methodology; Edit is the proposed upstream text. Recorded by Standardize on any branch |
Status values:
| Status | Meaning |
pending | Awaiting an apply pass — the default on a spec branch |
applied (date) | Written by an apply menu, with the date it was applied |
rejected (reason) | Declined by the user; the reason is recorded so it is not blindly re-proposed |
deferred | The user chose Defer in an apply menu (solo fast path included): the item stays in the backlog, keeps being counted by /akili-resume, and is re-offered at every later apply pass. Deferral is a visible postponement, never a terminal state |
superseded (reason) | The re-verify probe refuted the item's premise at apply time; closed without writing; the reason names what changed and, when known, which spec changed it |
upstreamed (date, report) | Collected into the named upstream report; closed on the project side. Terminal for upstream items only |
Apply Mode — Working the Pending Backlog
Runs only on the apply-capable branch (Branch Context — the pinned integration branch when the Integration Branch: pin exists, otherwise the default branch; never both). Invocation: "apply pending kaizen standardizations" (also "kaizen apply", "aplicar estandarizaciones kaizen"); /akili-archive offers it automatically when its own retrospective ran on the apply-capable branch, and /akili-resume recommends it there, by its pinned name. Input: every pending item in every entry file — not one spec's. Output: HITL-approved edits, a refreshed digest, stamped statuses, and — when the backlog holds upstream items — one upstream report.
- Collect. Scan
docs/specs/kaizen/*.mdfor items whoseStatusispendingordeferred. Process them in entry-filename lexical order — one deterministic order, so the same backlog yields the same result on any run. If there is nothing to apply, say so in one line and stop. An item the collector cannot parse (an unknownStatusencoding, a missingTarget, a non-table pending block) is this step's own named outcome, not a fall-through: list it in the pass report by file and position, leave itsStatusaspending, append one one-line note to the item, and move on — never guessed at, never silently skipped, never half-applied. Group by
Target— a file path, aKZ-idfordigest-updateitems, or the literalmethodologyforupstreamitems. Three outcomes, in this order: the first (Merge) applies toKZ-idtargets; the second and third (Dedupe, Decide) apply only to file targets.upstreamitems are exempt from all three — however many share themethodologytarget, and however theirEdittext differs, everyupstreamitem groups undermethodologyand is collected whole, unmerged, in step 4b:Case Rule digest-updateitems on the sameKZ-idMerge, never prompt: the highest proposed severity wins, source specs union, one digest row updated. Two branches hitting the same root cause is the expected case, not a conflict Byte-identical Edittext targeting the same fileDedupe: apply once; every contributing item flips to appliedciting that single applicationDiffering Edittext targeting the same fileDecide: quote both proposals side by side with their source entry files and let the user choose. Never apply both silently; never auto-pick a winner - Present the HITL menu over the grouped items — the same four options as the Standardize phase (Apply all / Apply selected / Defer / adjust).
3b. Re-verify. Before writing each item the user approved, run one bounded probe: confirm the Target still exists at HEAD, then confirm the one specific fact the Edit names with one grep or existence check — nothing wider than that. Three outcomes only:
- The probe holds → proceed to step 4.
- The probe is refuted → the item closes as
superseded (reason): never written; the reason names what changed. - The fact cannot be settled by a single check → present the item to the user as unverifiable, with the reason; the user decides apply / defer / reject. Re-verify never expands into an investigation and never re-reads the source spec, the archive, or the codebase beyond the one named fact.
upstream items are exempt from this probe: their Target is the literal methodology, not a path, and their Edit names no fact in this repository for a grep or existence check to confirm — they pass to step 4b unprobed.
For a digest-update item, the Target is a KZ-id, not a path: "exists at HEAD" means a row with that ID in the ## Active Lessons digest, or a lesson heading with that ID in any entry file under docs/specs/kaizen/; the fact probe is the item's recurrence claim (the source spec the item adds names a real entry file). An absent docs/specs/kaizen-log.md alone never supersedes it — the digest is created in the same pass.
- Apply what was approved and re-verified, per
Kind:standardization,guide-sync,factual-sweep— write the recorded 1–3 lines to the recorded target.trd-adr— allocate the next freeADR-MMMat this moment, sequentially in the processing order above, append the decision todocs/trd/trd.md, and flip the ADR it supersedes tosuperseded by ADR-MMM. Ifdocs/trd/trd.mddoes not exist, leave the itempending, add a one-line note in the item block saying why, and move on — never invent the file.digest-update— handled in step 5.upstream— handled in step 4b.
4b. Upstream report. Collect every approved upstream item into one file, docs/specs/kaizen/upstream-<YYYY-MM-DD>[-N].md (a numeric suffix on a same-day collision), written only on the apply-capable branch:
- Header: project, apply-capable branch (by pinned name), date, methodology version installed, item count.
- One row per item: lesson ID, source entry file, severity, one-line root cause, the proposed upstream edit verbatim from the item.
- Footer: the invocation the methodology maintainer runs to intake it (
/akili-proposewith the report as context) — a recommendation, not automation.
Flip each collected item's Status to upstreamed (<date>, <report path>). upstream items add no digest row and are never written into a guide, persona, template, or design doc. A scaffolded README.md under docs/specs/kaizen/ is never an upstream report. If no upstream items were approved this pass, skip this step and write no file.
- Refresh the digest in the same pass. This step is the
## Active Lessonstable's only writer: 0. Normalize first. Dedupe the digest's existing rows byID— a digest inherited from a hand edit or a pre-pin merge can carry duplicates — then re-enforce the 10-row cap through the retirement rule below, before any new row is added.- Apply the merged
digest-updateitems first (severity raises, added source specs, recurrence notes). - Then add a row for each newly applied lesson.
- Keep the table at 10 rows or fewer. If it would exceed 10, retire
Appliedrows — the ones institutionalized longest first. Never retire aDeferredrow or a row still linked to a pending item. - If
docs/specs/kaizen-log.mddoes not exist, create it with the header and the digest section only, on the apply-capable branch. - If it still carries a populated legacy
## Entriessection without the freeze note, add the freeze note (below) on this first apply pass. Historical entries are never rewritten, renumbered, or deleted.
- Apply the merged
- Stamp statuses back into each source entry file:
applied (date),rejected (reason),deferred,superseded (reason), orupstreamed (date, report). Nothing is silently dropped — a declined menu leaves every itempending, and the backlog is re-offered next pass.
Kaizen Log Format
docs/specs/kaizen-log.md holds one live section: the ## Active Lessons digest — same path, same columns, same semantics as before, and still the only kaizen content other AKILI commands read. Its single writer is Apply Mode. Per-retrospective content lives in the entry file (phase 4), not here.
# Kaizen Log
Continuous-improvement record for this project. The `## Active Lessons` digest below is
refreshed only by the `kaizen` skill's Apply Mode, on the apply-capable branch. Other AKILI
commands read only this table — keep it at 10 rows or fewer. Per-retrospective entries
live in `docs/specs/kaizen/`, one file per spec.
## Active Lessons
| ID | Lesson | Source Spec | Severity | Target | Standardized In | Status |
|---|---|---|---|---|---|---|
| KZ-changes--add-remember-me-1 | Define empty-state design tokens before any UI task that renders lists | changes/add-remember-me | Medium | Product | docs/specs/general-setup/design.md | Applied |
| KZ-002 | DTO boundary validations must be written as `AND IT MUST` constraints in requirements, never left implicit | bugfix/login-redirect | High | Product | docs/specs/general-setup/requirements.md | Applied |
## Entries
> **Frozen.** The entries below are historical. New retrospectives write one file per spec
> under `docs/specs/kaizen/`. Nothing here is rewritten, renumbered, or deleted.
### 2026-07-20 — changes/add-remember-me
<!-- historical entry, left exactly as written -->Both ID grammars coexist in the digest: legacy KZ-### rows keep their IDs, new rows carry KZ-<safe-spec-slug>-<n>.
Hard Rules
Branch Context
Every write decision in this skill turns on one question: which branch, if any, is apply-capable right now? Resolve it once per run and refer to the answer by name ("Branch Context") everywhere else. Plain git only — no host-specific API.
- Current branch:
git rev-parse --abbrev-ref HEAD. - Default branch — the pin first. The
Default Branch:line in the constitution summary of the rootAGENTS.md/CLAUDE.md./akili-constitutionwrites it, and every command already loads those files, so in a pinned project the resolution ends here. - No pin (legacy projects):
git symbolic-ref refs/remotes/origin/HEAD --short, stripping the leadingorigin/. This ref is unset in many clones until someone runsgit remote set-head origin --auto— an error here is normal, not exceptional; fall through quietly. - Still unresolved — the unique
main/masterrule. Among local andorigin/branches, if exactly one ofmainormasterexists, that is the default branch. If both exist, the result is unresolved — never guess. - Integration Branch: pin, and nothing else. The
Integration Branch: <name>line in the same constitution summary block, immediately afterDefault Branch:, is the sole source for this resolution. - Context value:
integrationwhen the current branch equals the integration pin from step 5; elsedefaultwhen it equals the default branch resolved in steps 2–4; elsespec. Unresolved or failed default-branch resolution still yieldsspec— deferring is always safe.
No fallback of any kind exists for step 5: no branch-name heuristic (develop, staging, …), no ref lookup, no merge-history inference. A missing pin means integration cannot occur; it is never inferred from git.
git config init.defaultBranch is never consulted at any step: it describes the name newly created repositories get, not the branch this repository integrates into, so it resolves the wrong branch silently.
Apply-capable predicate (defined once here; every other surface cites it by name): integration when the Integration Branch: pin exists; default when it does not. Never both — exactly one branch per project is apply-capable at any time. When the integration pin exists, a checkout of the default branch resolves to default and is non-writing: every gate that would otherwise write there records pending items instead and names the integration branch as the place to apply (Writable set, below).
Both pins naming the same branch: the integration pin is redundant. The context is default, it is apply-capable, and the skill says so in one line so the redundancy is visible rather than silently ignored.
On unresolved or failure — both main and master present, detached HEAD, no git repository — treat the context as a spec branch and defer: deferring is always safe, applying is not. Say so in one line and name the remedy — pin Default Branch: <name> in the constitution summary.
Writable set
| Branch Context | What this skill may write |
Spec branch (or unresolved), or the default branch while an Integration Branch: pin exists | The spec's own entry file docs/specs/kaizen/<safe-spec-slug>.md — nothing else. No persona, guide, template, design doc, TRD, or digest. (With the pin present, the default branch is held to this same restriction — it is not the writer while the pin stands.) |
| Apply-capable branch (the pinned integration branch when the pin exists, otherwise the default branch) | The above, plus HITL-approved shared files and the digest, through the Standardize menu or Apply Mode |
Standing rules
- Never block the archive (or any invoking command). Missing inputs or a declined menu → write a metrics-only or clean-run entry file and continue. The fallback write target is always the entry file, never the log.
- The digest has one writer: Apply Mode, on the apply-capable branch. No retrospective phase writes
## Active Lessonson any branch for any reason — recurrence included; it becomes adigest-updatepending item. - Accepted residual: while an
Integration Branch:pin exists, a spec branch cut from the default branch (a hotfix) does not see standardizations applied on the integration branch until the next release merge — the same visibility any developer has of unmerged sibling work. - Never edit a shared file without explicit HITL approval — and never from a spec branch, approval or not.
- Legacy
## Entriesare frozen: read them as history, never rewrite, renumber, or delete them. There is no migration step. - Digest capped at 10 Active Lessons; retire institutionalized lessons instead of letting the table grow.
- At most 3 lessons per retrospective; prefer zero over filler.
- Standardization edits are 1–3 lines; never rewrite whole documents.
- Consumers (
/akili-propose,/akili-specify,/akili-execute,/akili-resume) read only the## Active Lessonsdigest for lesson content, never## Entriesand never entry files. The single addition:/akili-resumecounts pending items underdocs/specs/kaizen/for its dashboard footer — a read-only count, not a lesson read.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

