akili-specs 2.6.0 → 2.7.0

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

@@ -92,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

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

@@ -173,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

@@ -121,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.

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

@@ -95,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:
 
@@ -288,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/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,14 @@ 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

package/README.md

@@ -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`

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/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/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` |
@@ -24,7 +25,7 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
 | [`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/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.6.0",
+  "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": {