agentleFS
JuankCadavidJuankCadavid/akili-specs/.claude/skills/kaizen/SKILL.md

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

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
  1. Very specific:

    Run the four phases in order.

    line 55
  2. Very specific:

    Every lesson names a root cause (apply 5W1H) and cites its evidence — file + section, e.g.

    line 84
  3. Distinctive:

    Prefer zero lessons over filler.

    line 86
  4. Very specific:

    Write the retrospective to docs/specs/kaizen/<safe-spec-slug>.md — one file per spec, outside the spec folder so it survives archiving:

    line 128
  5. Very specific:

    Create docs/specs/kaizen/ if it does not exist.

    line 132
  6. Very specific:

    Never prepend to ## Entries and never touch ## Active Lessons in docs/specs/kaizen-log.md — the apply phase on the apply-capable branch is …

    line 133
  7. Very specific:

    Keep the table at 10 rows or fewer.

    line 258
  8. Very specific:

    If docs/specs/kaizen-log.md does not exist, create it with the header and the digest section only, on the apply-capable branch.

    line 259
  9. Very specific:

    If it still carries a populated legacy ## Entries section without the freeze note, add the freeze note (below) on this first apply pass.

    line 260
  10. Distinctive:

    Every write decision in this skill turns on one question: which branch, if any, is apply-capable right now?

    line 299
  11. Very specific:

    No fallback of any kind exists for step 5: no branch-name heuristic (develop, staging, …), no ref lookup, no merge-history inference.

    line 308

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 apply-capable branch checked out and offers the pending backlog.

The loop runs in two phases with two different homes:

PhaseRuns whereWrites
Retrospective (Measure → Learn → Standardize → Record)any branchthe 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.

ConceptMeaningIn AKILI
Kai + ZenSmall changes that make things better, every day, foreverEvery /akili-archive is an improvement opportunity; the loop never "finishes"
Small steps (Maurer)Improvements so small they cannot fail or trigger resistanceStandardization 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 onesLearn step asks: "What is the smallest rule that would have prevented this rework?"
PDCA (Deming)Plan → Do → Check → ActPlan = the spec; Do = execute/test; Check = validate + Measure; Act = Standardize. The retrospective closes the cycle the pipeline opened
MUDAWaste: any activity that adds no valueRework attempts (defects), pivots (planning waste), token waste (oversized context, re-reading), stale docs (drift = inventory waste), quick-escalations (misrouted work). Measure = hunt MUDA
JidokaStop the line the moment a defect appearsAKILI 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 GENReal place, real thing, real facts — never speculateEvery 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 teachableThe ## Active Lessons digest row: one lesson, one line, one owner document
Standardize & repeatA fix becomes a standard, then the next improvement beginsApplied 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:

SignalSource
Reviewer FAIL rework attempts, HALTs, FATAL_FAILsexecution.md task entries
Pivotsexecution.md ## Pivot Record blocks
PRODUCT_BUG findingstest-report.md
Severe judgment-day findingsdesign.md / specify review notes, if recorded
Validation FAIL / WARN countsvalidation-report.md
Escalations from /akili-quick into this specdocs/specs/quick/quick-log.md, if applicable
Drift attributable to this specthe 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 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 as a Kind: upstream pending 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 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 a Kind: upstream pending 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: upstream pending 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 ContextWhat 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 existsThe 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:

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

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

KindOrigin
standardizationA lesson's proposed edit (phase 3)
digest-updateA 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)
upstreamA 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:

StatusMeaning
pendingAwaiting 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
deferredThe 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.

  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. An item the collector cannot parse (an unknown Status encoding, a missing Target, 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 its Status as pending, append one one-line note to the item, and move on — never guessed at, never silently skipped, never half-applied.
  2. Group by Target — a file path, a KZ-id for digest-update items, or the literal methodology for upstream items. Three outcomes, in this order: the first (Merge) applies to KZ-id targets; the second and third (Dedupe, Decide) apply only to file targets. upstream items are exempt from all three — however many share the methodology target, and however their Edit text differs, every upstream item groups under methodology and is collected whole, unmerged, in step 4b:

    CaseRule
    digest-update items on the same KZ-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 Edit text targeting the same fileDedupe: apply once; every contributing item flips to applied citing that single application
    Differing Edit text 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
  3. 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.

  1. 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 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.
    • 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-propose with 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.

  1. Refresh the digest in the same pass. This step is the ## Active Lessons table's only writer: 0. Normalize first. Dedupe the digest's existing rows by ID — 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.
    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, on the apply-capable branch.
    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.
  2. Stamp statuses back into each source entry file: applied (date), rejected (reason), deferred, superseded (reason), or upstreamed (date, report). 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 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.

  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.
  5. Integration Branch: pin, and nothing else. The Integration Branch: <name> line in the same constitution summary block, immediately after Default Branch:, is the sole source for this resolution.
  6. Context value: integration when the current branch equals the integration pin from step 5; else default when it equals the default branch resolved in steps 2–4; else spec. Unresolved or failed default-branch resolution still yields spec — 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 ContextWhat this skill may write
Spec branch (or unresolved), or the default branch while an Integration Branch: pin existsThe 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 Lessons on any branch for any reason — recurrence included; it becomes a digest-update pending 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 ## 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.