akili-specs 2.5.1 → 2.7.0

package/.claude/commands/akili-archive.md

@@ -1,5 +1,5 @@
 ---
-description: Archive a completed spec task, sync agent guides and CodeGraph, and keep the TRD current.
+description: Archive a completed spec task, run the Kaizen retrospective, sync agent guides and CodeGraph, and keep the TRD current.
 ---
 
 # Archive AKILI-SPECS Spec
@@ -8,7 +8,7 @@ Archive a completed AKILI-SPECS spec path after implementation, testing, and val
 
 Archiving preserves the full decision trail. It keeps active `docs/specs/` easier to scan while retaining proposal, requirements, design, tasks, execution notes, test evidence, and validation evidence for future review.
 
-> **Recommended model tier:** T5 Fast-Cheap. This is a format-following and file-moving job; a deep reasoning model is not required.
+> **Recommended model tier:** T5 Fast-Cheap. This is a format-following and file-moving job; a deep reasoning model is not required. The Kaizen Learn sub-step (Step 4.2) is a judgment task — if convenient, run it on a T3 Auditor model; otherwise keep the whole command on T5 and keep lessons few.
 
 ## Usage
 
@@ -71,6 +71,10 @@ docs/specs/archive/2026-05-16-bugfix--login-redirect/
    - `execution.md` if present
    - `test-report.md` if present
    - `validation-report.md` if present
+4. Read Kaizen inputs (each only if it exists):
+   - `docs/specs/kaizen-log.md`
+   - `docs/specs/drift-report.md`
+   - `docs/specs/quick/quick-log.md` (only if this spec escalated from `/akili-quick`)
 
 ### Step 1: Check Archive Readiness
 
@@ -88,6 +92,8 @@ If readiness is unclear, stop and ask the user whether to proceed, validate firs
 
 ### Step 2: Create Archive Summary
 
+Write the summary (and later the Kaizen log entry) following `cognitive-doc-design`: lead with the outcome, keep sections small, and prefer tables and checklists over prose.
+
 Before moving the folder, create or update:
 
 ```text
@@ -119,13 +125,35 @@ Before moving the folder, sync the project constitution with what the spec actua
    - Follow the inheritance convention from `/akili-constitution` Step 7 — if the project has no `## Module Guides` index yet, add it rather than inventing a parallel structure.
 3. **CodeGraph Refresh Hook:** Check if `.codegraph/` exists in the repository root. If it does, recommend that the user or environment runs a fresh CodeGraph indexing/update (e.g. running `codegraph index` or equivalent) so the graph reflects the new or reshaped modules.
 
-### Step 4: Move Folder
+### Step 4: Kaizen Retrospective
+
+Before moving the folder, **load the `kaizen` skill and follow its loop contract**: one bounded continuous-improvement pass over the completed spec — **Measure → Learn → Standardize → Record**. The pass reads only files already loaded in Step 0, produces at most 3 lessons and one log entry, and must never block the archive.
+
+#### 4.1 — Measure
+
+Extract the improvement signals listed in the skill's Measure table from the spec's own evidence: Reviewer FAIL rework attempts, HALTs and FATAL_FAILs, `## Pivot Record` blocks, PRODUCT_BUG findings, severe judgment-day findings, validation FAIL/WARN counts, `/akili-quick` escalations, and drift attributable to this spec.
+
+If every signal is clean, record a one-line **clean run** entry in Step 4.4 and skip 4.2–4.3.
+
+#### 4.2 — Learn
+
+Distill **0 to 3** lessons following the skill's hard rules: every lesson names a root cause and cites its evidence (file + section); generic lessons are banned; prefer zero lessons over filler; a repeated root cause increments recurrence and raises severity instead of duplicating. Classify each lesson's target as **Product** (this project) or **Methodology** (the root cause is AKILI itself).
+
+#### 4.3 — Standardize (HITL)
+
+For each lesson, propose exactly one minimal edit (1–3 lines) to the most durable home (constitution guides, `docs/specs/general-setup/` templates, `docs/ux-ui/design.md`, or `.agents/` personas — append-only). Methodology lessons get no local edit; record them for upstreaming to the AKILI methodology repository. Present the skill's approval menu (Apply all / Apply selected / Defer all / Type something); recommend "Apply all" when any High-severity lesson exists, otherwise "Defer all". **Every edit outside the kaizen log requires this approval.**
+
+#### 4.4 — Record
+
+Create or update `docs/specs/kaizen-log.md` using the skill's Kaizen Log Format: prepend the new entry under `## Entries`, refresh `## Active Lessons` (10 rows max, retire institutionalized lessons).
+
+### Step 5: Move Folder
 
 1. Ensure `docs/specs/archive/` exists.
 2. Move `docs/specs/$ARGUMENTS/` to `docs/specs/archive/YYYY-MM-DD-$SAFE_NAME/`.
 3. If the target archive folder already exists, do not overwrite it. Add a numeric suffix such as `-2` and report the final path.
 
-### Step 5: Report To User
+### Step 6: Report To User
 
 Present:
 
@@ -135,6 +163,7 @@ Present:
 4. unresolved follow-ups, if any
 5. whether the active spec directory is now clean
 6. constitution sync summary: guides created or updated, parent index entries touched, and whether a CodeGraph re-index is recommended
+7. Kaizen summary: metrics captured, lessons recorded (IDs), standardization actions applied or deferred, and any Methodology lessons suggested for upstreaming to the AKILI repo
 
 ## Error Handling
 
@@ -143,3 +172,5 @@ Present:
 - If validation has unresolved FAIL findings, recommend fixing or explicitly accepting risk before archive.
 - If moving the folder fails, leave the original folder in place and report the reason.
 - Do not delete spec folders as part of archiving; only move them into `docs/specs/archive/`.
+- The Kaizen retrospective must never block the archive. If retrospective inputs are missing or the user declines, append a metrics-only (or clean-run) entry to `docs/specs/kaizen-log.md` and continue to Step 5.
+- Never edit files outside `docs/specs/kaizen-log.md` without explicit user approval in Step 4.3.

package/.claude/commands/akili-constitution.md

@@ -119,6 +119,8 @@ Focus especially on:
 - Infrastructure expectations (e.g., AWS, deployment platforms, architectural rules, specific cloud components required)
 - Preferred `docs/specs/` taxonomy when the repo does not already imply one
 
+Use the `product-manager-toolkit` skill's **Customer Interview Guide** and **Hypothesis Template** as the question script. If the user has interview transcripts or raw customer feedback available, offer its `customer_interview_analyzer.py` helper to extract pain points, jobs-to-be-done, and themes before drafting.
+
 Ask only what is needed to avoid unstable assumptions.
 
 ---
@@ -127,7 +129,7 @@ Ask only what is needed to avoid unstable assumptions.
 
 Create or enhance `docs/prd.md` as a concise living document.
 
-**Primary skill:** `product-manager-toolkit`
+**Primary skill:** `product-manager-toolkit` — follow its **AKILI-SPECS Integration** section: the Required PRD structure below is canonical (never substitute the toolkit's own PRD templates); use its North Star Metric framework for "Goals & Success Metrics", jobs-to-be-done for "Target Personas", and its Hypothesis Template for "Assumptions". Write the document following `cognitive-doc-design`: lead with the answer, progressive disclosure, tables and checklists over prose.
 
 **PRD rules:**
 

package/.claude/commands/akili-execute.md

@@ -75,6 +75,7 @@ The Leader does not write production code itself unless the rework loop is exhau
    - `docs/specs/$ARGUMENTS/design.md`
    - `docs/specs/$ARGUMENTS/tasks.md`
 3. Read `docs/specs/$ARGUMENTS/execution.md` if it exists.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 4. Read the agent personas:
    - `.agents/leader.md`
    - `.agents/implementer.md`
@@ -133,6 +134,7 @@ Delegate to the Implementer with:
 - the project constitution references (`CLAUDE.md`, `AGENTS.md`, `docs/ux-ui/design.md`)
 - the recommended skill list from the task (e.g. `ui-ux-pro-max`, `react-doctor`, `nestjs-expert`)
 - any prior Reviewer feedback when this is a rework attempt
+- any Active Lessons from `docs/specs/kaizen-log.md` relevant to the task's domain (pass only the matching rows, never the full log)
 - the verification command to run before reporting completion
 
 The Implementer must keep changes minimal and within task scope, follow the design spec exactly unless the spec is clearly incomplete or contradictory, and run the verification before reporting completion.
@@ -171,7 +173,7 @@ Only after a Reviewer `PASS`:
 
 1. Update `tasks.md` from `[ ]` (or `[~]`) to `[x]`.
 2. Append a structured entry to `execution.md` (see log format below) covering every attempt in this task's loop.
-3. **Git Commit Staging:** Always follow the **AKILI Spec Reference** commit standard. Prefix the commit message with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`).
+3. **Git Commit Staging:** Always follow the **AKILI Spec Reference** commit standard. Prefix the commit message with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`). When writing a PR description for the spec's work, load `cognitive-doc-design` and follow its PR and Review Docs rules: state what to review first, what is intentionally out of scope, and link chained PRs.
 4. **Code Traceability:** Add file-level or block-level comment spec references (`// @akili-spec <spec-path>`) in critical or complex codebase additions to assist future audits.
 5. **Constitution Impact Check:** If the task created a new module/package, moved a module boundary, or changed a module's public surface, append a `## Constitution Impact: <Task ID>` block to `execution.md` recording:
    - which module was created or reshaped

package/.claude/commands/akili-propose.md

@@ -65,6 +65,7 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
    - `docs/specs/general-setup/`
    - package-level `CLAUDE.md` files
 4. Read nearby or related specs under `docs/specs/`.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
 
 ### Step 1: Classify Request Type & Route
@@ -120,6 +121,7 @@ Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
 
 **Scope Chunking:** If the user provides a very large or multi-faceted instruction (e.g., an entire epic or multiple distinct features), analyze whether the request should be split into multiple bounded proposals.
 - If it should be split, propose breaking it down to the user.
+- When recommending the build order of the resulting chunks, score them with RICE or MoSCoW from the `product-manager-toolkit` skill (AKILI-SPECS Integration section) instead of guessing.
 - Upon agreement, create the respective folders for each bounded change under `docs/specs/` and generate a `proposal.md` for each.
 
 Ask focused questions only when the proposal would otherwise depend on unstable assumptions.
@@ -143,6 +145,8 @@ Create a concise proposal with this structure:
 13. Success Criteria
 14. Next Step
 
+If an Active Lesson from `docs/specs/kaizen-log.md` applies to this change's domain, reflect it in Scope or Risks and cite its ID (e.g. `KZ-003`).
+
 ### Visual Reference
 
 Capture whatever visual source backs this change so `/akili-specify` can convert it into requirements, design, and tasks. Use the state that applies:

package/.claude/commands/akili-resume.md

@@ -78,6 +78,12 @@ If **multiple specs** are active, present a dashboard:
 Which spec do you want to resume? (or "all" for full briefing)
 ```
 
+If `docs/specs/kaizen-log.md` exists, append a Kaizen footer line to either format, reading ONLY the `## Active Lessons` table:
+
+```markdown
+Kaizen: 3 active lessons (latest: KZ-003 — empty-state tokens before list UI)
+```
+
 ### Step 3: Provide Full Briefing (if requested)
 
 If the user selects "all" or if there's only one spec, provide a detailed briefing for each:

package/.claude/commands/akili-specify.md

@@ -74,6 +74,7 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
    - A generated mockup under `docs/specs/$ARGUMENTS/mockup/`, `.stitch/designs`, or a `.stitch/DESIGN.md` reference → read those artifacts (screens, HTML, design tokens) and use `stitch-design` to interpret them.
    - Any mockup produced during `/akili-propose` counts as visual design context for the `Design Impact` steps below, exactly like a Figma link.
 4. Read nearby or dependent specs under `docs/specs/` that overlap with the requested path.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
 6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
 
@@ -94,11 +95,12 @@ Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
 
 **Scope Chunking:** If the user provides a very large instruction or epic, evaluate if it is too massive for a single spec.
 - If it spans multiple distinct modules or features, propose splitting the spec into multiple separate specs.
+- When recommending the build order of the split specs, score them with RICE or MoSCoW from the `product-manager-toolkit` skill (AKILI-SPECS Integration section) instead of guessing.
 - If the user agrees, create the separate folders under `docs/specs/` and draft a `proposal.md` or jump straight to the split documents (`requirements.md`, `design.md`, `tasks.md`) for each chunk.
 
 #### Step 1.2 — Write
 
-Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source.
+Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source. Write every spec document (`requirements.md`, `design.md`, `tasks.md`) following `cognitive-doc-design`: lead with the answer, progressive disclosure, and tables/checklists/scenarios over prose.
 
 Minimum content:
 
@@ -189,7 +191,7 @@ Use additional technical skills as needed:
 
 #### Step 2.2 — Write
 
-Generate `design.md` using `docs/specs/general-setup/design.md` as the format source.
+Generate `design.md` using `docs/specs/general-setup/design.md` as the format source. Apply relevant Active Lessons from `docs/specs/kaizen-log.md` and cite the lesson ID next to the design decision it shaped.
 
 Minimum content:
 
@@ -287,7 +289,7 @@ Preferred UI/UX skill rule:
 Present a clear summary of the generated tasks on the screen, including:
 - A high-level list of the tasks to be implemented so the user understands the plan without reading the full document.
 - An **Estimated Lines of Code (LOC)** output for the entire spec.
-- A **PR Strategy Recommendation**: If the estimate exceeds ~400 LOC or the task graph is highly complex, recommend splitting the implementation into multiple Pull Requests and suggest logical boundaries (e.g., "PR 1: Backend/API, PR 2: Frontend UI").
+- A **PR Strategy Recommendation**: If the estimate exceeds ~400 LOC or the task graph is highly complex, recommend splitting the implementation into multiple Pull Requests and suggest logical boundaries (e.g., "PR 1: Backend/API, PR 2: Frontend UI"). When PRs are chained, note that their descriptions should follow `cognitive-doc-design` review-empathy rules (what to review first, what is out of scope, link previous/next PR).
 
 Then explicitly ask the user how to proceed, providing these options:
 

package/.claude/skills/cognitive-doc-design/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cognitive-doc-design
+description: "Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## When to Use
+
+Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
+
+Use it especially for:
+
+- PR descriptions and review notes.
+- Contributor or maintainer guides.
+- Architecture, workflow, or onboarding docs.
+- Any doc that currently feels long, dense, or hard to scan.
+
+## Critical Patterns
+
+| Pattern | Rule |
+|---------|------|
+| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
+| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
+| Chunking | Group related information into small sections. Keep flat lists short. |
+| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
+| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
+| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
+
+## Documentation Shape
+
+Use this default structure unless the repo already provides a stronger template:
+
+```markdown
+# <Outcome-oriented title>
+
+<One paragraph: what changed, who it helps, and why it matters.>
+
+## Quick path
+
+1. <First action>
+2. <Second action>
+3. <Verification or expected result>
+
+## Details
+
+| Topic | Decision |
+|-------|----------|
+| <area> | <concise explanation> |
+
+## Checklist
+
+- [ ] <Reader can confirm this>
+- [ ] <Reader can confirm that>
+
+## Next step
+
+<Link or action that continues the workflow.>
+```
+
+## PR and Review Docs
+
+When documenting a PR, reduce reviewer burnout by making the review path explicit:
+
+- State what to review first.
+- State what is intentionally out of scope.
+- Link the previous and next PR when work is chained.
+- Keep each section focused on one decision or unit of work.
+- Use checklists for acceptance criteria and verification.
+
+## Commands
+
+```bash
+# Check markdown files changed in the current branch
+git diff --name-only -- '*.md'
+
+# Inspect PR changed-line count for cognitive load
+gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
+```

package/.claude/skills/kaizen/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: kaizen
+description: "Trigger: kaizen, retrospective, continuous improvement, mejora continua, /akili-archive Kaizen step. Run the bounded Kaizen retrospective: Measure → Learn → Standardize → Record."
+license: MIT
+metadata:
+  author: Juan Carlos Cadavid — jcadavid.com
+  version: "1.0"
+  inspired-by: "Kaizen Institute glossary (kaizen.com), 'El Método Kaizen' (small-steps approach, Robert Maurer), 'Emprendiendo Kaizen' (INTI, 2019, ISBN 978-950-532-415-6)"
+---
+
+# 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), or
+- the user explicitly requests a kaizen retrospective / continuous-improvement pass over a spec or project.
+
+The retrospective is **bounded**: one pass, at most 3 lessons, one log entry. 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. Read only artifacts already loaded by the invoking command.
+
+### 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 | `docs/specs/drift-report.md`, if present |
+
+If every signal is clean (zero rework, no pivots, no product bugs, no severe findings), record a one-line **clean run** entry in phase 4 and skip phases 2–3. A clean spec teaches nothing new — say so.
+
+### 2. Learn
+
+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.
+- If the same root cause already exists in `## Active Lessons`, do not duplicate it — increment its recurrence note and raise its severity (a repeat is a strong standardization signal).
+- 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.
+
+### 3. Standardize (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 log and recommend upstreaming it to the AKILI methodology repository.
+
+Assign a severity: **High** = caused a HALT, pivot, or PRODUCT_BUG; **Medium** = caused rework or a severe finding; **Low** = friction only. Then present the menu:
+
+1. **Apply all** (make every proposed edit now)
+2. **Apply selected** (user picks by lesson ID)
+3. **Defer all** (record proposals in the log; apply in a later spec)
+4. **Type something** (adjust a proposal before applying)
+
+Recommend option 1 when any High-severity lesson exists, otherwise option 3. Appending to the kaizen log is automatic; **every edit outside the log requires this approval**.
+
+### 4. Record
+
+Create or update `docs/specs/kaizen-log.md` (it lives outside spec folders so it survives archiving):
+
+1. If the file does not exist, create it with the header and both sections from the format below.
+2. Prepend the new entry under `## Entries` (newest first).
+3. Refresh `## Active Lessons`: add new lessons; keep the table at **10 rows or fewer**; retire lessons whose rule now lives in the constitution or templates (mark `Retired` — the guide carries the rule from now on).
+
+## Kaizen Log Format
+
+```markdown
+# Kaizen Log
+
+Continuous-improvement record for this project, updated automatically by
+`/akili-archive` (Kaizen Retrospective, powered by the `kaizen` skill).
+Other AKILI commands read only the `## Active Lessons` table below —
+keep it at 10 rows or fewer.
+
+## Active Lessons
+
+| ID | Lesson | Source Spec | Severity | Target | Standardized In | Status |
+|---|---|---|---|---|---|---|
+| KZ-003 | 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
+
+### 2026-07-20 — changes/add-remember-me
+
+**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-003 — 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: add an empty-state token check to the Design Impact checklist in
+    `docs/specs/general-setup/design.md`. → **Applied 2026-07-20 (user-approved)**
+
+### 2026-07-19 — bugfix/session-refresh — clean run
+
+No rework, pivots, product bugs, or severe findings. No lessons recorded.
+```
+
+## Hard Rules
+
+- **Never block the archive** (or any invoking command). Missing inputs or a declined menu → append a metrics-only or clean-run entry and continue.
+- **Never edit files outside `docs/specs/kaizen-log.md` without explicit HITL approval** in phase 3.
+- 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, never `## Entries`.

package/.claude/skills/product-manager-toolkit/SKILL.md

@@ -1,12 +1,31 @@
 ---
 name: product-manager-toolkit
-description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development.
+description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. In AKILI-SPECS projects, follow the AKILI-SPECS Integration section first.
+metadata:
+  adapted-for: "AKILI-SPECS methodology by Juan Carlos Cadavid — jcadavid.com"
 ---
 
 # Product Manager Toolkit
 
 Essential tools and frameworks for modern product management, from discovery to delivery.
 
+## AKILI-SPECS Integration
+
+When this skill is loaded inside the AKILI-SPECS methodology, this section takes precedence over the generic workflows below. Each tool has one precise moment in the flow:
+
+| AKILI moment | Use from this toolkit |
+|---|---|
+| `/akili-constitution` Step 2 (Clarify Missing Business Context) | The **Customer Interview Guide** and **Hypothesis Template** as the question script. If the user has interview transcripts or raw customer feedback, offer `scripts/customer_interview_analyzer.py` to extract pain points, jobs-to-be-done, and themes — they feed the PRD's Problem Statement and Target Personas. |
+| `/akili-constitution` Step 3 (PRD) | **The AKILI 9-section PRD structure is canonical** — never substitute this toolkit's PRD templates for it. Use the toolkit to fill those sections well: **North Star Metric** framework for "Goals & Success Metrics", **jobs-to-be-done** for "Target Personas", the **Hypothesis Template** for "Assumptions, Dependencies, & Constraints". |
+| `/akili-propose` / `/akili-specify` Scope Chunking | When an epic splits into multiple specs, score the chunks with **RICE** (or **MoSCoW** for a quick pass) to recommend the build order. Treat each candidate spec as a row: `name,reach,impact,confidence,effort` → `scripts/rice_prioritizer.py`. |
+| `/akili-propose` (Change track) | The **Feature Brief** mindset maps to `proposal.md`: problem → hypothesis → success criteria. Do not create a separate brief document. |
+
+Rules inside AKILI-SPECS:
+
+- The scripts are optional helpers (they need Python); never block a flow on them — the frameworks work as reasoning guides on their own.
+- Skip the Go-to-Market and Stakeholder Management sections during constitution work; they are out of scope for `docs/prd.md`.
+- Output always lands in AKILI artifacts (`docs/prd.md`, `proposal.md`, spec folders) — never in standalone PM documents.
+
 ## Quick Start
 
 ### For Feature Prioritization

package/.claude/skills/product-manager-toolkit/references/prd_templates.md

@@ -1,5 +1,7 @@
 # Product Requirements Document (PRD) Templates
 
+> **AKILI-SPECS note:** In AKILI-SPECS projects, `docs/prd.md` MUST follow the 9-section structure defined in `/akili-constitution` Step 3 (Overview & Purpose → Problem Statement → Target Personas → Goals & Success Metrics → Scope In/Out → User Stories → Acceptance Criteria → Assumptions/Dependencies/Constraints → Open Questions). The templates below are reference material for filling those sections well — or for PM work outside the methodology — never a replacement structure.
+
 ## Standard PRD Template
 
 ### 1. Executive Summary

package/CHANGELOG.md

@@ -10,6 +10,20 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.7.0] - 2026-07-20
+
+### Added
+- **New packaged `cognitive-doc-design` skill** (by gentleman-programming, Apache-2.0): six patterns for docs that reduce cognitive load (lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, review empathy). Wired into the methodology: `/akili-constitution` (PRD writing), `/akili-specify` (all spec documents + chained-PR descriptions), `/akili-execute` (PR and review docs), and `/akili-archive` (archive summary and Kaizen log entries).
+
+### Changed
+- **`product-manager-toolkit` adapted to AKILI-SPECS:** new **AKILI-SPECS Integration** section maps each tool to its exact moment in the flow — Customer Interview Guide + Hypothesis Template as the question script for `/akili-constitution` Step 2 (with the interview analyzer offered when transcripts exist), North Star Metric / jobs-to-be-done / Hypothesis Template to fill the canonical 9-section PRD in Step 3, and RICE/MoSCoW to order scope chunks when `/akili-propose` or `/akili-specify` split an epic into multiple specs. The PRD templates reference now marks the AKILI structure as canonical, and Go-to-Market content is explicitly out of scope for constitution work.
+- **Clear end-of-run summaries in every CLI command:** `akili install` now closes with an **Install Summary** block (per-tool `installed | overwritten | skipped | legacy cleaned` counts with target paths, totals when installing for multiple tools, an explicit dry-run banner, and contextual next steps — `--force` hint, OpenCode restart, `akili doctor` verification). `akili doctor` closes with a **Doctor Summary** (per-tool `HEALTHY | REPAIRED | INCOMPLETE` status with `ok | missing | fixed` counts and repair suggestions). `akili update` closes with an **Update Summary** (version before → after, install type, and how to verify). `akili list` prints a totals line (commands | skills | resources + package version). Overwrites are now counted separately from fresh installs.
+## [2.6.0] - 2026-07-20
+
+### Added
+- **The Kaizen Loop in `/akili-archive`:** every archive now runs a bounded continuous-improvement retrospective — **Measure** (rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, drift) → **Learn** (0–3 root-cause lessons with cited evidence; generic lessons banned) → **Standardize** (minimal 1–3 line edits to constitution guides, general-setup templates, design tokens, or `.agents/` personas — always HITL-approved) → **Record** (append to the new accumulative `docs/specs/kaizen-log.md`, with a capped `## Active Lessons` digest). No new command: Kaizen is a step inside `/akili-archive` and never blocks archiving. Lessons target the **Product** or the **Methodology** itself (flagged for upstreaming to this repo).
+- **New packaged `kaizen` skill** (`.claude/skills/kaizen/SKILL.md`), authored by Juan Carlos Cadavid — jcadavid.com, inspired by the Kaizen Institute glossary, Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen* (2019). It encodes the philosophy-to-engineering mapping (PDCA, MUDA, Jidoka, Gemba/3 GEN, 5W1H, LUP), the loop contract, and the kaizen-log format.
+- **Kaizen-aware commands:** `/akili-propose`, `/akili-specify`, and `/akili-execute` read the `## Active Lessons` digest so past mistakes shape new specs and task delegation; `/akili-resume` shows the active-lesson count in its dashboard.
 ## [2.5.1] - 2026-07-19
 
 ### Added

package/README.md

@@ -11,9 +11,9 @@
 
 # AKILI
 
-### Supercharge Claude Code, OpenCode, and Google Antigravity with constitution-first spec intelligence
+### Supercharge Claude Code, OpenCode, and Google Antigravity with constitution-first, self-improving spec intelligence
 
-**Durable product context · traceable requirements · governed releases · 100% local methodology files**
+**Durable product context · traceable requirements · governed releases · a methodology that learns from every spec · 100% local methodology files**
 
 <p>
   <a href="https://www.npmjs.com/package/akili-specs"><img alt="npm version" src="https://img.shields.io/npm/v/akili-specs?style=for-the-badge&label=npm"></a>
@@ -79,6 +79,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `api-design-principles`
   - `aws-serverless`
   - `brainstorming`
+  - `cognitive-doc-design`
   - `error-handling-patterns`
   - `frontend-design`
   - `gsap-core`
@@ -90,6 +91,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `gsap-timeline`
   - `gsap-utils`
   - `judgment-day`
+  - `kaizen`
   - `nestjs-expert`
   - `product-manager-toolkit`
   - `react-doctor`
@@ -507,7 +509,7 @@ See the full [Command Reference](docs/commands/README.md) for detailed pages per
 | `/akili-execute <spec-path>` | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
 | `/akili-test <spec-path>` | Adding or running test evidence | `test-report.md` with requirement-to-test traceability |
 | `/akili-validate <spec-path>` | Checking implementation against the spec | `validation-report.md` with pass, warning, failure, and remediation items |
-| `/akili-archive <spec-path>` | Closing completed work after validation | Archived spec folder under `docs/specs/archive/` with `archive-summary.md`, synced agent guides, CodeGraph re-index reminder |
+| `/akili-archive <spec-path>` | Closing completed work after validation | Archived spec folder under `docs/specs/archive/` with `archive-summary.md`, Kaizen retrospective appended to `docs/specs/kaizen-log.md`, synced agent guides, CodeGraph re-index reminder |
 | `/akili-audit` | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
 | `/akili-resume` | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | `/akili-seo <site-domain>` | Auditing deployed SEO and Search Console state | `seo-setup-report.md`, `seo-audit-report.md` |
@@ -539,6 +541,30 @@ Lite mode does not skip rigor. It keeps the documents short, but every requireme
 | Task | A small executable unit linked to requirements and design sections |
 | Report | Evidence that the implementation was tested and validated |
 | Archive | Completed AKILI-SPECS history moved under `docs/specs/archive/` |
+| Kaizen | The continuous-improvement loop that turns each spec's evidence into lessons and standards |
+
+## The Kaizen Loop
+
+Other methodologies execute specs. **AKILI learns from every spec.**
+
+AKILI embeds the Japanese Kaizen philosophy of continuous improvement (改善 — *kai* change, *zen* better) as an executable step, powered by the packaged `kaizen` skill (authored by [Juan Carlos Cadavid](https://jcadavid.com), inspired by the Kaizen Institute glossary, Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen*). Every `/akili-archive` automatically runs a bounded retrospective — no extra command, no extra ceremony:
+
+```text
+┌─────────┐    ┌─────────┐    ┌──────────────┐    ┌──────────┐
+│ MEASURE │ ─▶ │  LEARN  │ ─▶ │ STANDARDIZE  │ ─▶ │  REPEAT  │
+│ rework, │    │ 0–3 root│    │ constitution │    │ next spec│
+│ pivots, │    │ -cause  │    │ templates,   │    │ reads the│
+│ bugs    │    │ lessons │    │ guides (HITL)│    │ lessons  │
+└─────────┘    └─────────┘    └──────────────┘    └──────────┘
+        every /akili-archive · logged in docs/specs/kaizen-log.md
+```
+
+- **Measure:** hunt MUDA (waste) in the spec's own evidence — Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation warnings, drift.
+- **Learn:** distill 0–3 lessons with a named root cause and cited evidence (Gemba: real facts, never speculation). Generic lessons are banned.
+- **Standardize:** propose 1–3 line edits to constitution guides, spec templates, design tokens, or agent personas — always human-approved. Small steps, never rewrites.
+- **Record:** append to the accumulative `docs/specs/kaizen-log.md`; a capped `## Active Lessons` digest is then read by `/akili-propose`, `/akili-specify`, and `/akili-execute` so past mistakes shape new work, and shown by `/akili-resume`.
+
+The loop improves on two levels: **Product** lessons harden the project you are building, while **Methodology** lessons (root causes in AKILI itself) are flagged for upstreaming — so the methodology learns from every tool built with it. This is the meaning behind the name: *akili* is Swahili for intelligence, and intelligence that does not learn is not intelligence.
 
 ## Spec Folder Shape
 
@@ -729,7 +755,7 @@ Fallback rule:
 - `/akili-execute` orchestrates a Leader → Implementer → Reviewer rework loop (max 3 retries) to implement tasks from an approved spec path.
 - `/akili-test` runs a Leader → Tester(s) harness: the Leader partitions testing into suites and delegates each to a Tester subagent (inline for trivial/Lite work; one Tester per independent suite, in parallel, otherwise). It validates requirement-to-test traceability, explicitly checking for negative constraints and strict boundaries.
 - `/akili-validate` audits implementation conformance against the spec (including rigorous boundary validations) and constitutional baseline.
-- `/akili-archive` preserves completed specs under `docs/specs/archive/` after validation, syncs agent guides (child `CLAUDE.md`/`AGENTS.md` + the parent `## Module Guides` index) from the spec's `## Constitution Impact` notes, and recommends a CodeGraph re-index.
+- `/akili-archive` preserves completed specs under `docs/specs/archive/` after validation, runs the Kaizen retrospective (measure → learn → standardize → record) appending to `docs/specs/kaizen-log.md`, syncs agent guides (child `CLAUDE.md`/`AGENTS.md` + the parent `## Module Guides` index) from the spec's `## Constitution Impact` notes, and recommends a CodeGraph re-index.
 - `/akili-seo` operates outside the main spec lifecycle: it provisions Google Search Console ownership for a domain and produces a standalone SEO audit under `docs/specs/seo/<domain>/`. Run it any time after deployment; rerun after major content or schema changes.
 
 ## Multi-Agent Harness Engineering

package/bin/akili.js

@@ -227,19 +227,23 @@ function shouldInclude(type, args) {
 function copySingleFile(sourcePath, targetPath, args) {
   ensureDirectory(path.dirname(targetPath), args.dryRun);
 
-  if (fs.existsSync(targetPath) && !args.force) {
+  const exists = fs.existsSync(targetPath);
+
+  if (exists && !args.force) {
     console.log(`  ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
-    return { installed: 0, skipped: 1 };
+    return { installed: 0, overwritten: 0, skipped: 1 };
   }
 
-  const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+  const action = exists ? "overwrite" : "install";
   console.log(`  ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
 
   if (!args.dryRun) {
     fs.copyFileSync(sourcePath, targetPath);
   }
 
-  return { installed: 1, skipped: 0 };
+  return exists
+    ? { installed: 0, overwritten: 1, skipped: 0 }
+    : { installed: 1, overwritten: 0, skipped: 0 };
 }
 
 function copyDirectoryContents(sourceDir, targetDir, args) {
@@ -247,19 +251,21 @@ function copyDirectoryContents(sourceDir, targetDir, args) {
 
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
   let installed = 0;
+  let overwritten = 0;
   let skipped = 0;
 
   for (const entry of entries) {
     const sourcePath = path.join(sourceDir, entry.name);
     const targetPath = path.join(targetDir, entry.name);
+    const exists = fs.existsSync(targetPath);
 
-    if (fs.existsSync(targetPath) && !args.force) {
+    if (exists && !args.force) {
       console.log(`  ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
       skipped += 1;
       continue;
     }
 
-    const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+    const action = exists ? "overwrite" : "install";
     console.log(`  ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
 
     if (!args.dryRun) {
@@ -269,10 +275,11 @@ function copyDirectoryContents(sourceDir, targetDir, args) {
         errorOnExist: false,
       });
     }
-    installed += 1;
+    if (exists) overwritten += 1;
+    else installed += 1;
   }
 
-  return { installed, skipped };
+  return { installed, overwritten, skipped };
 }
 
 function getToolRegistryInfo(tool, args) {
@@ -328,6 +335,7 @@ function installTool(tool, args) {
   const { rootPath, paths } = getToolRegistryInfo(tool, args);
 
   let installed = 0;
+  let overwritten = 0;
   let skipped = 0;
 
   console.log(`\n${colors.cyan}${tool.toUpperCase()} target: ${rootPath}${colors.reset}`);
@@ -337,51 +345,47 @@ function installTool(tool, args) {
     console.log(`  ${colors.green}Legacy cleanup complete.${colors.reset}`);
   }
 
+  const add = (result) => {
+    installed += result.installed;
+    overwritten += result.overwritten;
+    skipped += result.skipped;
+  };
+
   if (shouldInclude("commands", args)) {
     for (const targetCommands of paths.commands) {
-      const result = copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args);
-      installed += result.installed;
-      skipped += result.skipped;
+      add(copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args));
     }
   }
 
   if (shouldInclude("skills", args)) {
-    const result = copyDirectoryContents(SOURCE_SKILLS, paths.skills, args);
-    installed += result.installed;
-    skipped += result.skipped;
+    add(copyDirectoryContents(SOURCE_SKILLS, paths.skills, args));
   }
 
   if (shouldInclude("resources", args)) {
     for (const scriptName of RESOURCE_SCRIPTS) {
-      const result = copySingleFile(
-        path.join(SOURCE_SCRIPTS, scriptName),
-        path.join(paths.resources, "scripts", scriptName),
-        args
+      add(
+        copySingleFile(
+          path.join(SOURCE_SCRIPTS, scriptName),
+          path.join(paths.resources, "scripts", scriptName),
+          args
+        )
       );
-      installed += result.installed;
-      skipped += result.skipped;
     }
 
     for (const templateName of AGENT_TEMPLATES) {
-      const result = copySingleFile(
-        path.join(SOURCE_TEMPLATES, templateName),
-        path.join(paths.resources, "templates", templateName),
-        args
+      add(
+        copySingleFile(
+          path.join(SOURCE_TEMPLATES, templateName),
+          path.join(paths.resources, "templates", templateName),
+          args
+        )
       );
-      installed += result.installed;
-      skipped += result.skipped;
     }
 
-    const mcpResult = copySingleFile(
-      SOURCE_MCP_EXAMPLE,
-      path.join(paths.resources, ".mcp.json.example"),
-      args
-    );
-    installed += mcpResult.installed;
-    skipped += mcpResult.skipped;
+    add(copySingleFile(SOURCE_MCP_EXAMPLE, path.join(paths.resources, ".mcp.json.example"), args));
   }
 
-  return { installed, skipped };
+  return { rootPath, installed, overwritten, skipped, cleaned };
 }
 
 function detectInstallType() {
@@ -539,25 +543,63 @@ function runUpdate(args) {
   const packageDir = resolveInstalledPackageDir(installType);
   const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
   printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
+
+  console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
+  console.log(`${colors.cyan}Update Summary${colors.reset}`);
+  if (versionAfter && versionAfter !== versionBefore) {
+    console.log(`  Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installType} install)`);
+  } else if (versionAfter) {
+    console.log(`  Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installType} install)`);
+  } else {
+    console.log(`  Package: updated from v${versionBefore} (${installType} install; new version could not be read)`);
+  }
+  console.log(`  Files: reinstalled with --force for ${selectedTools(args).join(", ")} (see Install Summary above)`);
+  console.log(`  Verify: ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}`);
+}
+
+function summaryCounts(result) {
+  return `${colors.green}installed ${result.installed}${colors.reset} | overwritten ${result.overwritten} | ${colors.yellow}skipped ${result.skipped}${colors.reset}${result.cleaned ? ` | legacy cleaned ${result.cleaned}` : ""}`;
 }
 
 function runInstall(args) {
-  let installed = 0;
-  let skipped = 0;
+  const tools = selectedTools(args);
+  const results = [];
 
-  for (const tool of selectedTools(args)) {
-    const result = installTool(tool, args);
-    installed += result.installed;
-    skipped += result.skipped;
+  for (const tool of tools) {
+    results.push({ tool, ...installTool(tool, args) });
   }
 
-  console.log(`\nDone. Installed: ${installed} | Skipped: ${skipped}`);
-  if (skipped > 0 && !args.force) {
-    console.log(`Use ${colors.yellow}--force${colors.reset} to overwrite existing files.`);
+  const totals = results.reduce(
+    (acc, r) => ({
+      installed: acc.installed + r.installed,
+      overwritten: acc.overwritten + r.overwritten,
+      skipped: acc.skipped + r.skipped,
+      cleaned: acc.cleaned + r.cleaned,
+    }),
+    { installed: 0, overwritten: 0, skipped: 0, cleaned: 0 }
+  );
+
+  console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
+  console.log(`${colors.cyan}Install Summary${colors.reset} — akili-specs v${currentVersion}${args.dryRun ? ` ${colors.yellow}(dry-run: no files were written)${colors.reset}` : ""}`);
+  for (const r of results) {
+    console.log(`  ${r.tool.toUpperCase().padEnd(12)} ${summaryCounts(r)}`);
+    console.log(`  ${"".padEnd(12)} → ${r.rootPath}`);
+  }
+  if (results.length > 1) {
+    console.log(`  ${"TOTAL".padEnd(12)} ${summaryCounts(totals)}`);
   }
 
-  if (selectedTools(args).includes("opencode") && !args.dryRun) {
-    console.log(`Restart ${colors.cyan}OpenCode${colors.reset} for installed commands and skills to be loaded.`);
+  console.log(`\n${colors.cyan}Next steps:${colors.reset}`);
+  if (totals.skipped > 0 && !args.force) {
+    console.log(`  - ${totals.skipped} existing file(s) were preserved. Re-run with ${colors.yellow}--force${colors.reset} to overwrite them.`);
+  }
+  if (tools.includes("opencode") && !args.dryRun) {
+    console.log(`  - Restart ${colors.cyan}OpenCode${colors.reset} for installed commands and skills to be loaded.`);
+  }
+  if (args.dryRun) {
+    console.log(`  - Re-run without ${colors.yellow}--dry-run${colors.reset} to apply the changes above.`);
+  } else {
+    console.log(`  - Verify the installation with ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}.`);
   }
 }
 
@@ -574,6 +616,9 @@ function runList() {
   RESOURCE_SCRIPTS.forEach((name) => console.log(`  ${formatPath(path.join("scripts", name))}`));
   AGENT_TEMPLATES.forEach((name) => console.log(`  ${formatPath(path.join("templates", name))}`));
   console.log("  .mcp.json.example");
+
+  const resourceCount = RESOURCE_SCRIPTS.length + AGENT_TEMPLATES.length + 1;
+  console.log(`\n${colors.cyan}Summary:${colors.reset} ${commands.length} commands | ${skills.length} skills | ${resourceCount} resources (akili-specs v${currentVersion})`);
 }
 
 function hasInstalledCommand(targetCommandsList, name) {
@@ -587,6 +632,7 @@ function hasInstalledCommand(targetCommandsList, name) {
 
 function doctorTool(tool, args) {
   const { rootPath, paths } = getToolRegistryInfo(tool, args);
+  let okCount = 0;
   let missing = 0;
   let fixed = 0;
 
@@ -597,6 +643,7 @@ function doctorTool(tool, args) {
     for (const command of listCommands()) {
       const ok = hasInstalledCommand(paths.commands, command);
       if (ok) {
+        okCount += 1;
         console.log(`  ${colors.green}OK${colors.reset} ${command}`);
       } else {
         if (args.fix) {
@@ -617,6 +664,7 @@ function doctorTool(tool, args) {
     for (const skill of listSkills()) {
       const ok = fs.existsSync(path.join(paths.skills, skill, "SKILL.md"));
       if (ok) {
+        okCount += 1;
         console.log(`  ${colors.green}OK${colors.reset} ${skill}`);
       } else {
         if (args.fix) {
@@ -646,6 +694,7 @@ function doctorTool(tool, args) {
     for (const check of resourceChecks) {
       const ok = fs.existsSync(check.dest);
       if (ok) {
+        okCount += 1;
         console.log(`  ${colors.green}OK${colors.reset} ${check.dest}`);
       } else {
          if (args.fix) {
@@ -660,23 +709,41 @@ function doctorTool(tool, args) {
     }
   }
 
-  return { missing, fixed };
+  return { rootPath, ok: okCount, missing, fixed };
 }
 
 function runDoctor(args) {
-  let missingTotal = 0;
-  let fixedTotal = 0;
-  
+  const results = [];
+
   for (const tool of selectedTools(args)) {
-    const { missing, fixed } = doctorTool(tool, args);
-    missingTotal += missing;
-    fixedTotal += fixed;
+    results.push({ tool, ...doctorTool(tool, args) });
+  }
+
+  const missingTotal = results.reduce((acc, r) => acc + r.missing, 0);
+  const fixedTotal = results.reduce((acc, r) => acc + r.fixed, 0);
+
+  console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
+  console.log(`${colors.cyan}Doctor Summary${colors.reset} — akili-specs v${currentVersion}`);
+  for (const r of results) {
+    const status =
+      r.missing > 0
+        ? `${colors.red}INCOMPLETE${colors.reset}`
+        : r.fixed > 0
+        ? `${colors.cyan}REPAIRED${colors.reset}`
+        : `${colors.green}HEALTHY${colors.reset}`;
+    console.log(`  ${r.tool.toUpperCase().padEnd(12)} ${status}  ${colors.green}ok ${r.ok}${colors.reset} | ${colors.red}missing ${r.missing}${colors.reset} | fixed ${r.fixed}`);
+    console.log(`  ${"".padEnd(12)} → ${r.rootPath}`);
   }
 
-  console.log(`\nDone. Missing: ${missingTotal} | Fixed: ${fixedTotal}`);
   if (missingTotal > 0) {
-    console.log(`Run ${colors.cyan}akili doctor --fix${colors.reset} to auto-repair missing files.`);
+    console.log(`\n${colors.cyan}Next steps:${colors.reset}`);
+    console.log(`  - Run ${colors.cyan}akili doctor --tool ${args.tool} --fix${colors.reset} to auto-repair the ${missingTotal} missing file(s).`);
+    console.log(`  - Or run ${colors.cyan}akili update${colors.reset} to refresh the package and reinstall everything.`);
     process.exitCode = 1;
+  } else if (fixedTotal > 0) {
+    console.log(`\nAll issues repaired: ${fixedTotal} file(s) restored.`);
+  } else {
+    console.log(`\nAll checks passed. Your installation is complete and healthy.`);
   }
 }
 

package/docs/README.md

@@ -1,6 +1,6 @@
 # AKILI Documentation
 
-AKILI is the documented form of the AKILI-SPECS methodology: a constitution-first, spec-driven workflow for Claude Code and OpenCode.
+AKILI is the documented form of the AKILI-SPECS methodology: a constitution-first, self-improving spec-driven workflow for Claude Code and OpenCode.
 
 Use this documentation when you want the human-facing reference. The installable source prompts and skills remain under `.claude/commands/` and `.claude/skills/`.
 
@@ -26,6 +26,8 @@ Use this documentation when you want the human-facing reference. The installable
 /akili-archive <spec-path>
 ```
 
+Every `/akili-archive` closes with the **Kaizen Loop** — a bounded retrospective (Measure → Learn → Standardize → Record, via the packaged `kaizen` skill) that appends lessons to `docs/specs/kaizen-log.md` so the next spec starts smarter. See [flow.md](flow.md#8-the-kaizen-loop).
+
 Use `/akili-resume` at the start of any session to see a dashboard of all active specs and where each one stands.
 
 Use `/akili-audit` independently to detect drift between specs and codebase reality at any time.

package/docs/cli.md

@@ -56,6 +56,13 @@ akili install --tool both --local
 | `akili doctor` | Check whether expected files are installed |
 | `akili help` | Show help |
 
+Every command closes with a clear end-of-run summary:
+
+- **`install`** — an **Install Summary** with per-tool `installed | overwritten | skipped` counts (plus legacy cleanup), target paths, totals for multi-tool installs, a dry-run banner when `--dry-run` is used, and contextual next steps (`--force` hint, OpenCode restart, `akili doctor` verification).
+- **`doctor`** — a **Doctor Summary** with a per-tool `HEALTHY | REPAIRED | INCOMPLETE` status, `ok | missing | fixed` counts, and repair suggestions (`--fix` or `akili update`).
+- **`update`** — an **Update Summary** with the version change (`before → after`), install type, and the verification command, after the changelog of what changed.
+- **`list`** — a totals line: commands, skills, resources, and the package version.
+
 ## Options
 
 | Option | Applies To | Purpose |

package/docs/commands/README.md

@@ -13,7 +13,7 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 | [`/akili-execute <spec-path>`](akili-execute.md) | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code/docs changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
 | [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence via the Leader → Tester(s) harness | `test-report.md` |
 | [`/akili-validate <spec-path>`](akili-validate.md) | Auditing conformance before completion | `validation-report.md` |
-| [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` |
+| [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` + Kaizen retrospective entry in `docs/specs/kaizen-log.md` |
 | [`/akili-audit`](akili-audit.md) | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
 | [`/akili-resume`](akili-resume.md) | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | [`/akili-seo <site-domain>`](akili-seo.md) | Setting up GSC ownership and SEO audit evidence | `seo-setup-report.md`, `seo-audit-report.md` |

package/docs/commands/akili-archive.md

@@ -1,6 +1,6 @@
 # `/akili-archive`
 
-Move a completed spec into historical archive after implementation, testing, and validation.
+Move a completed spec into historical archive after implementation, testing, and validation, running the Kaizen retrospective along the way.
 
 ## Usage
 
@@ -58,8 +58,20 @@ Before moving the folder, the command consumes the `## Constitution Impact` note
 - updates root-guide statements the change made stale
 - recommends a CodeGraph re-index when `.codegraph/` exists
 
+## Kaizen Retrospective
+
+Before moving the folder, the command loads the packaged `kaizen` skill and runs one bounded continuous-improvement pass — **Measure → Learn → Standardize → Record**:
+
+- **Measure:** extracts improvement signals from the spec's evidence (Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, quick escalations, drift).
+- **Learn:** distills 0–3 lessons, each with a named root cause and cited evidence; generic lessons are banned. Lessons target the **Product** or the **Methodology** (flagged for upstreaming to the AKILI repo).
+- **Standardize:** proposes 1–3 line edits to constitution guides, `general-setup` templates, design tokens, or `.agents/` personas via an approval menu. Every edit outside the kaizen log requires approval.
+- **Record:** appends the entry to the accumulative `docs/specs/kaizen-log.md` and refreshes its `## Active Lessons` digest (10 rows max), which `/akili-propose`, `/akili-specify`, `/akili-execute`, and `/akili-resume` read.
+
+A clean spec records a one-line clean-run entry. The retrospective never blocks the archive.
+
 ## Guardrails
 
 - Do not delete completed specs.
 - Do not overwrite an existing archive folder.
 - If archive readiness is unclear, ask whether to validate first, proceed with accepted risk, or keep the spec active.
+- The Kaizen retrospective never blocks the archive and never edits files outside `docs/specs/kaizen-log.md` without approval.

package/docs/commands/akili-execute.md

@@ -23,6 +23,7 @@ Reads:
 - `docs/specs/<spec-path>/design.md`
 - `docs/specs/<spec-path>/tasks.md`
 - `docs/specs/<spec-path>/execution.md` when present
+- `docs/specs/kaizen-log.md` when present — only the `## Active Lessons` digest; the Leader passes matching rows to the Implementer per task
 - Constitution docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`)
 - `CLAUDE.md` and `AGENTS.md`
 - `.agents/leader.md`, `.agents/implementer.md`, `.agents/reviewer.md`

package/docs/commands/akili-propose.md

@@ -53,6 +53,8 @@ Creates or updates:
 docs/specs/<spec-path>/proposal.md
 ```
 
+If `docs/specs/kaizen-log.md` exists, the command reads its `## Active Lessons` digest and reflects applicable lessons in the proposal's Scope or Risks, citing their IDs (e.g. `KZ-003`).
+
 ## Proposal Sections
 
 - Document Control (records `Type: Bug | Change | Trivial`)

package/docs/commands/akili-resume.md

@@ -23,7 +23,7 @@ The command performs a four-step scan:
 
 1. **Scan Active Specs** — lists all directories under `docs/specs/` (excluding `archive/`)
 2. **Determine Phase & Progress** — for each spec, identifies current phase (PROPOSE → SPECIFY → EXECUTE → TEST → VALIDATE → ARCHIVE), task progress, last action, and blockers
-3. **Present Dashboard** — shows a visual dashboard with progress bars and status for each active spec
+3. **Present Dashboard** — shows a visual dashboard with progress bars and status for each active spec; if `docs/specs/kaizen-log.md` exists, appends a Kaizen footer line with the active-lesson count and the latest lesson (read from the `## Active Lessons` digest only)
 4. **Recommend Next Command** — suggests the next command based on current phase
 
 ## Output

package/docs/commands/akili-specify.md

@@ -32,6 +32,7 @@ Reads context from:
 - `docs/ux-ui/design.md`
 - `docs/trd/trd.md`
 - related specs under `docs/specs/`
+- `docs/specs/kaizen-log.md` when present — only the `## Active Lessons` digest; relevant lessons are applied and cited by ID in design decisions
 - root and package-level agent guidance files
 
 ## Outputs

package/docs/flow.md

@@ -54,7 +54,7 @@ You: /akili-validate changes/add-remember-me
 AI:  Creates validation-report.md with PASS/WARN/FAIL/BLOCKED findings
 
 You: /akili-archive changes/add-remember-me
-AI:  Moves completed work into docs/specs/archive/ and refreshes CodeGraph
+AI:  Runs the Kaizen retrospective (appends docs/specs/kaizen-log.md), moves completed work into docs/specs/archive/, and refreshes CodeGraph
 
 Independent Auditing:
 You: /akili-audit
@@ -128,6 +128,7 @@ For Legacy and Active-AKILI-SPECS modes, CodeGraph is preferred when `.codegraph
 | `docs/specs/<spec-path>/test-report.md` | `/akili-test` | Requirement-to-test matrix and coverage gaps |
 | `docs/specs/<spec-path>/validation-report.md` | `/akili-validate` | Final conformance audit |
 | `docs/specs/drift-report.md` | `/akili-audit` | Conformance auditing of documentation vs. codebase reality |
+| `docs/specs/kaizen-log.md` | `/akili-archive` | Accumulated metrics and root-cause lessons; the `## Active Lessons` digest is read by `/akili-propose`, `/akili-specify`, `/akili-execute`, and `/akili-resume` |
 | `docs/specs/archive/.../archive-summary.md` | `/akili-archive` | Historical closure record |
 
 ## Review Gates
@@ -144,7 +145,7 @@ AKILI keeps humans in control at each important transition.
 | Execution | Each completed task has verification evidence |
 | Testing | Key requirements have automated or accepted manual evidence |
 | Validation | No unresolved FAIL findings remain |
-| Archive | Warnings and follow-ups are accepted |
+| Archive | Warnings and follow-ups are accepted; Kaizen lessons are recorded and standardizations approved or deferred |
 
 ## Documentation Depth
 
@@ -307,3 +308,22 @@ OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy o
 the project's `AGENTS.md` / `CLAUDE.md`. It is **guidance only** — no `model:` frontmatter, no
 installer changes — and it enforces **author ≠ auditor** (Reviewer model ≠ Implementer model). See
 [model-routing.md](model-routing.md) for the tiers, principles, and the default registry.
+
+### 8. The Kaizen Loop
+
+AKILI embeds Kaizen — continuous improvement through small, disciplined steps — as an executable
+retrospective inside `/akili-archive`, powered by the packaged `kaizen` skill (authored by
+Juan Carlos Cadavid — jcadavid.com). Every archive runs one bounded pass:
+
+* **Measure:** hunt waste (MUDA) in the spec's own evidence — Reviewer rework attempts, pivots,
+  PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, drift.
+* **Learn:** distill 0–3 lessons, each with a named root cause and cited evidence. Generic lessons
+  are banned; a clean spec records a one-line clean-run entry instead.
+* **Standardize:** propose 1–3 line edits to constitution guides, `general-setup` templates, design
+  tokens, or `.agents/` personas. **Every edit outside the kaizen log requires human approval.**
+* **Record:** append to the accumulative `docs/specs/kaizen-log.md`. Its capped `## Active Lessons`
+  digest (10 rows max) is the only part other commands read.
+
+Lessons target either the **Product** (this project) or the **Methodology** itself — Methodology
+lessons are flagged for upstreaming to the AKILI repository, so the methodology learns from every
+tool built with it. The retrospective never blocks the archive.

package/docs/model-routing.md

@@ -65,7 +65,7 @@ the suites, and a Tester ideally runs on a different model than the Implementer
 | `/akili-test` → **Tester(s)** | T2 | Test authoring + verification per suite. Prefer a different model than the Implementer (author ≠ tester). |
 | `/akili-validate` | T3 | Deep conformance audit. |
 | `/akili-audit` | T4 + T3 | Drift detection over large context, judged critically. |
-| `/akili-archive` | T5 | Cheap, fast summarization of closed work. |
+| `/akili-archive` | T5 | Cheap, fast summarization of closed work. (Kaizen Learn sub-step: T3 optional.) |
 | `/akili-seo` | T3 + T5 | Audit findings (T3) plus setup/formatting steps (T5). |
 
 **author ≠ auditor enforcement.** In the registry, T2 (Coder) and T3 (Auditor) must resolve to

package/docs/openspec-comparison.md

@@ -27,6 +27,7 @@ This repository borrows useful documentation and workflow ideas from OpenSpec wh
 | Existing projects | Brownfield-friendly workflow | Explicit existing-project constitution mode with optional CodeGraph analysis |
 | Validation | Workflow validation through commands | Dedicated `/akili-test` and `/akili-validate` reports before archive |
 | SEO | Not a core workflow in OpenSpec | `/akili-seo` handles Google Search Console setup and audits |
+| Continuous improvement | Not a core workflow in OpenSpec | The Kaizen Loop: `/akili-archive` runs a bounded retrospective and later commands read the accumulated `## Active Lessons` digest |
 | Package target | `@fission-ai/openspec` | `akili-specs` |
 
 ## Practical Takeaway

package/docs/skills/README.md

@@ -12,6 +12,7 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
 | [`api-design-principles`](api-design-principles.md) | REST and GraphQL API design and review | `/akili-constitution`, `/akili-specify`, `/akili-validate` |
 | [`aws-serverless`](aws-serverless.md) | Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK | `/akili-constitution`, `/akili-specify`, `/akili-execute` |
 | [`brainstorming`](brainstorming.md) | Clarifying ideas, scope, options, and trade-offs before implementation | `/akili-propose`, `/akili-specify` |
+| [`cognitive-doc-design`](cognitive-doc-design.md) | Writing human-facing docs that reduce cognitive load (lead with the answer, progressive disclosure, tables over prose) | `/akili-constitution`, `/akili-specify`, `/akili-execute` (PR docs), `/akili-archive` |
 | [`error-handling-patterns`](error-handling-patterns.md) | Exceptions, Result patterns, graceful degradation, reliability | `/akili-specify`, `/akili-execute`, `/akili-validate` |
 | [`frontend-design`](frontend-design.md) | Distinctive frontend UI and UX implementation | `/akili-constitution`, `/akili-specify`, `/akili-execute`, `/akili-test` |
 | [`gsap-core`](gsap-core.md) | Core GSAP tweens, easing, stagger, responsive and reduced-motion animation | `/akili-specify`, `/akili-execute` |
@@ -22,8 +23,9 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
 | [`gsap-scrolltrigger`](gsap-scrolltrigger.md) | Scroll-driven animation, pinning, scrub, parallax | `/akili-specify`, `/akili-execute` |
 | [`gsap-timeline`](gsap-timeline.md) | Sequenced animations and playback control | `/akili-specify`, `/akili-execute` |
 | [`gsap-utils`](gsap-utils.md) | GSAP utilities such as clamp, mapRange, random, snap, wrap | `/akili-execute` |
+| [`kaizen`](kaizen.md) | Bounded continuous-improvement retrospective (Measure → Learn → Standardize → Record); authored by Juan Carlos Cadavid — jcadavid.com | `/akili-archive` |
 | [`nestjs-expert`](nestjs-expert.md) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
-| [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
+| [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
 | [`react-doctor`](react-doctor.md) | React diagnostics after changes | `/akili-test`, `/akili-validate` |
 | [`seo-audit`](seo-audit.md) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo`, `/akili-validate` |
 | [`shadcn-ui`](shadcn-ui.md) | shadcn/ui components, forms, themes, Tailwind integration | `/akili-specify`, `/akili-execute`, `/akili-validate` |

package/docs/skills/cognitive-doc-design.md

@@ -0,0 +1,31 @@
+# `cognitive-doc-design`
+
+## Purpose
+
+Designs documentation that reduces cognitive load, using six patterns: lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, and review empathy. AKILI generates many human-facing documents (PRD, TRD, requirements, reports, summaries) — this skill defines how to write them so readers scan, understand, and verify quickly. Authored by gentleman-programming (Apache-2.0).
+
+## Use When
+
+- Writing or upgrading any human-facing AKILI document: PRD, UX/UI design, TRD, requirements, design, reports, archive summaries.
+- Writing PR descriptions and review notes during `/akili-execute` (its review-empathy rules reduce reviewer burnout).
+- Any doc that currently feels long, dense, or hard to scan.
+
+## Core Rules
+
+- Put the decision, action, or outcome first — context comes after.
+- Start with the happy path, then details, edge cases, and references.
+- Group related information into small sections; keep flat lists short.
+- Use headings, labels, callouts, and summaries as signposts.
+- Prefer tables, checklists, examples, and templates over prose that must be remembered.
+- For PRs: state what to review first, what is out of scope, and link chained PRs.
+
+## Best Paired Commands
+
+- `/akili-constitution` — writing `docs/prd.md`, the UX/UI design doc, and the TRD.
+- `/akili-specify` — writing `requirements.md`, `design.md`, and `tasks.md`.
+- `/akili-execute` — writing PR descriptions and review notes.
+- `/akili-archive` — writing `archive-summary.md` and Kaizen log entries (one-point lessons are recognition over recall).
+
+## Source
+
+- `../../.claude/skills/cognitive-doc-design/SKILL.md`

package/docs/skills/kaizen.md

@@ -0,0 +1,30 @@
+# `kaizen`
+
+**Author:** Juan Carlos Cadavid — [jcadavid.com](https://jcadavid.com)
+
+## Purpose
+
+Turns the Japanese Kaizen philosophy of continuous improvement into an executable, bounded retrospective: **Measure → Learn → Standardize → Record**. Every archived spec leaves the project — and the methodology itself — slightly better than it found them. Inspired by the Kaizen Institute glossary (kaizen.com), Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen* (2019).
+
+## Use When
+
+- `/akili-archive` reaches its **Kaizen Retrospective** step (the primary, automatic trigger).
+- The user explicitly requests a kaizen retrospective or continuous-improvement pass over a spec or project.
+
+## Core Rules
+
+- **Measure** hunts MUDA (waste) in the spec's own evidence: Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, quick escalations, drift.
+- **Learn** distills 0–3 lessons; each names a root cause (5W1H) and cites evidence (Gemba: real facts, never speculation). Generic lessons are banned; prefer zero over filler. Lessons target the **Product** or the **Methodology** (flagged for upstreaming to the AKILI repo).
+- **Standardize** proposes one minimal edit (1–3 lines) per lesson to the most durable home; every edit outside the kaizen log requires human approval via a numbered menu.
+- **Record** appends to the accumulative `docs/specs/kaizen-log.md`; the `## Active Lessons` digest is capped at 10 rows and institutionalized lessons are retired.
+- The retrospective **never blocks the archive** — missing inputs or a declined menu produce a metrics-only or clean-run entry.
+
+## Best Paired Commands
+
+- `/akili-archive` — runs the retrospective automatically as its Kaizen Retrospective step.
+- `/akili-propose`, `/akili-specify`, `/akili-execute` — read the `## Active Lessons` digest so past mistakes shape new work.
+- `/akili-resume` — shows the active-lesson count in the dashboard.
+
+## Source
+
+- `../../.claude/skills/kaizen/SKILL.md`

package/docs/skills/product-manager-toolkit.md

@@ -2,20 +2,20 @@
 
 ## Purpose
 
-Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking.
+Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking. Adapted for AKILI-SPECS: its **AKILI-SPECS Integration** section maps each tool to one precise moment in the flow, and the AKILI 9-section PRD structure is canonical over the toolkit's own templates.
 
 ## Use When
 
-- Creating or improving `docs/prd.md`.
-- Clarifying personas, goals, scope, success metrics, or non-goals.
-- Prioritizing features or deciding whether work should proceed.
+- Creating or improving `docs/prd.md` (the AKILI structure wins; the toolkit fills its sections well — North Star Metric, jobs-to-be-done, Hypothesis Template).
+- Clarifying personas, goals, scope, success metrics, or non-goals (`/akili-constitution` Step 2 uses its Customer Interview Guide as the question script; the interview analyzer extracts pain points from transcripts).
+- Ordering scope chunks with RICE or MoSCoW when `/akili-propose` or `/akili-specify` split an epic into multiple specs.
 - Turning discovery into requirements.
 
 ## Best Paired Commands
 
-- `/akili-constitution` for project PRD baseline.
-- `/akili-propose` for intent and scope.
-- `/akili-specify` for behavior requirements.
+- `/akili-constitution` for business-context questions (Step 2) and the project PRD baseline (Step 3).
+- `/akili-propose` for intent, scope, and chunk ordering.
+- `/akili-specify` for behavior requirements and split-spec ordering.
 
 ## Source
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {