Kaizen

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-archive reaches 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-archive finishes a retrospective with the default branch checked out and offers the pending backlog.

The loop runs in two phases with two different homes:

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 on a spec branch, it declines in one line ("Apply Mode runs only on the default 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.

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:

Most recent report means the highest Date header inside the report files, 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 report file at all. 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), write a one-line clean run entry file in phase 4 and skip phases 2–3. A clean spec teaches nothing new — say so.

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 lesson in 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-### or KZ-<safe-spec-slug>-<n>) — do not duplicate it. Record a digest-update pending item instead: Target = that KZ-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 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 rules
• docs/ux-ui/design.md — missing tokens or visual rules
• .agents/ personas — harness-role rules (append-only, never rewrite)
• Methodology lessons: no local edit — record the proposal in the entry file and recommend upstreaming it to the AKILI methodology repository.
• Dual (Product + Methodology) lessons: both, not either — the local edit follows the branch gate below, and the upstream recommendation is recorded in the entry file.

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:

The menu, on the default branch:

1. Apply all — make every proposed edit in this pass
2. Apply selected — user picks by lesson ID
3. Defer all — record the proposals as deferred; they stay in the backlog and are re-offered at every later apply pass
4. 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 no such edit happens at all, approved or not.

Standardize decides; Record writes. On a spec branch the pending items are composed here and land in the entry file in phase 4; on the default 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:

1. Derive the filename from the spec path with the archive's $SAFE_NAME rule (/ → --): changes/feature-a → changes--feature-a.md. No date prefix — the date lives in the entry's Document Control.
2. 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.
3. Create docs/specs/kaizen/ if it does not exist. In a legacy project this is the only structural change the retrospective makes.
4. Never prepend to ## Entries and never touch ## Active Lessons in docs/specs/kaizen-log.md — the apply phase on the default 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 |

## 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:

Status values:

Apply Mode — Working the Pending Backlog

Runs only on the default branch (Branch Context). Invocation: "apply pending kaizen standardizations" (also "kaizen apply", "aplicar estandarizaciones kaizen"); /akili-archive offers it automatically when its own retrospective ran on the default branch, and /akili-resume recommends it. Input: every pending item in every entry file — not one spec's. Output: HITL-approved edits, a refreshed digest, and stamped statuses.

1. Collect. Scan docs/specs/kaizen/*.md for items whose Status is pending or deferred. 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.

2. Group by Target — a file path, or a KZ-id for digest-update items. Three outcomes, in this order:

   Case	Rule
   digest-update items on the same KZ-id	Merge, 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 Edit text targeting the same file	Dedupe: apply once; every contributing item flips to applied citing that single application
   Differing Edit text targeting the same file	Decide: 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

3. Present the HITL menu over the grouped items — the same four options as the Standardize phase (Apply all / Apply selected / Defer / adjust).

4. Apply what was approved, per Kind:

   • standardization, guide-sync, factual-sweep — write the recorded 1–3 lines to the recorded target.
   • trd-adr — allocate the next free ADR-MMM at this moment, sequentially in the processing order above, append the decision to docs/trd/trd.md, and flip the ADR it supersedes to superseded by ADR-MMM. If docs/trd/trd.md does not exist, leave the item pending, add a one-line note in the item block saying why, and move on — never invent the file.
   • digest-update — handled in step 5.

5. Refresh the digest in the same pass. This step is the ## Active Lessons table's only writer:

   1. Apply the merged digest-update items first (severity raises, added source specs, recurrence notes).
   2. Then add a row for each newly applied lesson.
   3. Keep the table at 10 rows or fewer. If it would exceed 10, retire Applied rows — the ones institutionalized longest first. Never retire a Deferred row or a row still linked to a pending item.
   4. If docs/specs/kaizen-log.md does not exist, create it with the header and the digest section only.
   5. If it still carries a populated legacy ## Entries section without the freeze note, add the freeze note (below) on this first apply pass. Historical entries are never rewritten, renumbered, or deleted.

6. Stamp statuses back into each source entry file: applied (date), rejected (reason), or deferred. Nothing is silently dropped — a declined menu leaves every item pending, 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 default 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: is the checked-out branch the default branch? Resolve it once per run and refer to the answer by name ("Branch Context") everywhere else. Plain git only — no host-specific API.

1. Current branch: git rev-parse --abbrev-ref HEAD.
2. Default branch — the pin first. The Default Branch: line in the constitution summary of the root AGENTS.md / CLAUDE.md. /akili-constitution writes it, and every command already loads those files, so in a pinned project the resolution ends here.
3. No pin (legacy projects): git symbolic-ref refs/remotes/origin/HEAD --short, stripping the leading origin/. This ref is unset in many clones until someone runs git remote set-head origin --auto — an error here is normal, not exceptional; fall through quietly.
4. Still unresolved — the unique main/master rule. Among local and origin/ branches, if exactly one of main or master exists, that is the default branch. If both exist, the result is unresolved — never guess.

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.

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

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 default branch. No retrospective phase writes ## Active Lessons on any branch for any reason — recurrence included; it becomes a digest-update pending item.
• Never edit a shared file without explicit HITL approval — and never from a spec branch, approval or not.
• Legacy ## Entries are 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 Lessons digest for lesson content, never ## Entries and never entry files. The single addition: /akili-resume counts pending items under docs/specs/kaizen/ for its dashboard footer — a read-only count, not a lesson read.