incitaciones 0.2.0 → 0.3.1

package/pi-package/skills/whisper/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: whisper
+description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing"
+metadata:
+  installed-from: "incitaciones"
+---
+---
+name: whisper
+description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan to beads, decommission, and knowledge routing. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission worktree'."
+tools: Read, Write, Edit, Bash
+---
+
+# Whisper — Accumulated Operational Knowledge
+
+Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates operational knowledge and planning context across all your work. Works with or without beads issue tracking.
+
+## Directory Layout
+
+```
+~/.whisper/
+  rules.md                          ← Global agent behavior rules (bd remember equiv)
+
+  repos/
+    github.com/user/repo/
+      env.md                        ← Repo-wide: deploy commands, infra facts, auth quirks
+      branches/
+        branch-slug/                ← One slot per branch (/ in name → -- in slug)
+          context.md                ← Branch anchor: repo, branch, beads epic ID, status
+          plan.md                   ← Narrative implementation plan
+          notes.md                  ← Free-form scratch and findings
+          agents/                   ← Optional sub-agent files when work is split across agents
+      worktrees/
+        worktree-name/              ← One slot per worktree (basename of worktree path)
+          env.md                    ← Worktree-specific: ports, venvs, credentials, local-only setup
+```
+
+**Branch slug rule:** `git rev-parse --abbrev-ref HEAD | sed 's|/|--|g'`
+
+**Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
+
+## Knowledge Routing
+
+When a session learns something worth keeping, route it by scope:
+
+| Scope | Test | Destination |
+|---|---|---|
+| **Global** | True for every repo and every project | `~/.whisper/rules.md` — append, don't overwrite |
+| **Repo-wide infra** | True regardless of which branch or feature you're on (deploy behavior, gateway/timeout limits, log retention, auth quirks) | `~/.whisper/repos/<host>/<repo>/env.md` — create or extend |
+| **Branch-specific** | Only matters for the work on *this* epic/branch | `~/.whisper/repos/<host>/<repo>/branches/<slug>/notes.md`, or `bd note <epic-id>` if beads is available |
+| **Worktree setup** | Credentials, service IDs, ports, venv/docker specifics for *this checkout* | `~/.whisper/repos/<host>/<repo>/worktrees/<name>/env.md` |
+| **Universal agent rule** | A standing instruction for how the agent should behave, independent of any branch or repo | `bd remember` if available, else `~/.whisper/rules.md` |
+
+**Rules:**
+- **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
+- **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
+- **Search first.** Before creating a new entry, check if one already exists for the same topic.
+- If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
+
+## Modes
+
+Determine mode from how the skill is triggered:
+
+| Trigger | Mode |
+|---|---|
+| `/w init` or `~/.whisper/` does not exist | **init** |
+| `/w` or `/w status` | **status** |
+| `/w check` or called by `renew` | **check** |
+| `/w link [<path>]` or "link plan" | **link** |
+| `/w decommission` | **decommission** |
+
+See each reference file for the full procedure:
+
+- `references/init.md`
+- `references/check.md`
+- `references/status.md`
+- `references/link.md`
+- `references/decommission.md`
+
+## Rules
+
+- Never run `git worktree remove` automatically — always print the command for the user to execute.
+- Never close beads issues during decommission — only defer. Closing is intentional.
+- **One epic per branch, children via `--parent`, not flat siblings.**
+- **`env.md` is shared and immutable across branch switches.** Never overwrite it during init or check — only create if absent.
+- **Branch slug sanitization is mandatory.** Always run `sed 's|/|--|g'` on the branch name before using it as a directory path.
+- **Worktree reuse across branches is normal, not an edge case.** Expect multiple slots to accumulate in `branches/` over time.
+- **Legacy layout is still the common case.** Most worktrees never needed multiple branch slots — only migrate when a mismatch is detected.
+- This skill is self-contained. Do not rely on `create-plan`, `park`, or `create-handoff` having `~/.whisper/` awareness.
+- If `bd` is not initialized in the repo, skip beads steps gracefully and note what was skipped.

package/pi-package/skills/whisper/references/check.md

@@ -0,0 +1,33 @@
+# Check
+
+Validate the workspace before starting work. Detects stale branch slots and worktree reuse. Called automatically by `renew` when `~/.whisper/` exists.
+
+## Steps
+
+1. Get repo URL and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   ```
+
+2. **If `~/.whisper/` doesn't exist:** offer full init:
+   ```
+   ⚠ ~/.whisper/ not found. Run `/w init` to create the workspace.
+   ```
+
+3. **If `context.md` exists:** output one confirmation line and return.
+   ```
+   ✓ Workspace active: ~/.whisper/repos/<repo>/branches/<slug>/
+   ```
+
+4. **If the branch directory doesn't exist:**
+   ```
+   ⚠ No workspace slot for branch: <branch>
+     ~/.whisper/repos/<repo>/branches/<slug>/ does not exist yet.
+
+   Activate new slot? [Y/n]
+   ```
+   - Y → run **init** for the current branch.
+   - N → print "Staying without a slot. Run `/w init` when ready." and stop.

package/pi-package/skills/whisper/references/decommission.md

@@ -0,0 +1,53 @@
+# Decommission
+
+Safely wind down a worktree or branch: defer open work under the branch epic, record a final note, then print the removal command.
+
+## Steps
+
+1. Run **check** first. Confirm slot exists before decommissioning.
+
+2. Get repo URL and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   context_path="$branch_dir/context.md"
+   ```
+
+3. Read `beads-epic:` from `context.md`.
+
+4. If beads is available, get all open work under that epic:
+   ```bash
+   bd children <epic-id> --json 2>/dev/null
+   ```
+
+5. If any open children found, defer them:
+   ```bash
+   bd defer <id>
+   ```
+
+6. Defer the epic itself:
+   ```bash
+   bd defer <epic-id>
+   ```
+
+7. Record the decommission as a note on the epic:
+   ```bash
+   bd note <epic-id> "Decommissioned: branch <branch> on <date>. State: <summary>. Resume via: /w init on branch <branch> — bd search '<branch>' will find this epic."
+   ```
+
+8. Print the removal command — do NOT run it:
+   ```
+   Ready to remove worktree. Run:
+     git worktree remove <path>
+
+   Deferred epic <epic-id> and <n> children. To find them later:
+     bd list --status deferred --label branch:<branch>
+   ```
+
+## Rules
+
+- Never run `git worktree remove` automatically — always print the command.
+- Never close beads issues during decommission — only defer. Closing is intentional.
+- Branch slots in `~/.whisper/` are not automatically removed when a branch is merged. The slot serves as an archive; the epic (found via `bd search`) can be reused if the same branch name comes back.

package/pi-package/skills/whisper/references/init.md

@@ -0,0 +1,103 @@
+# Init
+
+Create `~/.whisper/` and the current workspace slot.
+
+## Steps
+
+1. Get context:
+   ```bash
+   pwd
+   git rev-parse --abbrev-ref HEAD
+   basename $(git rev-parse --show-toplevel 2>/dev/null)   # repo name
+   git rev-parse --git-common-dir 2>/dev/null              # confirms worktree vs main
+   date +%Y-%m-%d
+   ```
+
+2. Create `~/.whisper/` if it doesn't exist:
+   ```bash
+   mkdir -p ~/.whisper/repos
+   ```
+
+3. Compute the repo path and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   ```
+
+4. Create the repo & branch directory:
+   ```bash
+   mkdir -p ~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   wk_dir=$(basename "$(git rev-parse --git-common-dir 2>/dev/null || echo '.git')" | sed 's|\.git$||')
+   [ -n "$wk_dir" ] && mkdir -p ~/.whisper/repos/"${repo_url}"/worktrees/"${wk_dir}"
+   ```
+
+5. Create `~/.whisper/rules.md` if it doesn't exist:
+   ```markdown
+   # Global Agent Rules
+
+   > Standing instructions for the agent, independent of any repo or branch.
+   > Append here for rules that apply everywhere.
+   ```
+
+6. Create the repo `env.md` if it doesn't exist:
+   ```markdown
+   # Environment — <repo-name>
+
+   > Repo-wide setup knowledge. True regardless of which branch or worktree.
+   > Deploy commands, gateway limits, auth quirks that apply everywhere.
+   > Worktree-specific setup (ports, venvs, local creds) goes in worktrees/<name>/env.md
+   ```
+
+7. Create the worktree `env.md` if it doesn't exist:
+   ```markdown
+   # Worktree — <worktree-name>
+
+   > Worktree-specific setup. Credentials, ports, venv/docker specifics for THIS checkout only.
+   ```
+
+8. Create `context.md`:
+   ```markdown
+   # Workspace Context — <full-branch-name>
+
+   repo: <repo-url>
+   branch: <full-branch-name>
+   worktree: <worktree-dir-name>
+   path: <absolute-path>
+   created: <YYYY-MM-DD>
+   beads-epic:
+   ```
+
+9. Create `plan.md` stub:
+   ```markdown
+   # Plan — <full-branch-name>
+
+   > No plan yet. Write a plan here, then run `/w link` to create beads issues.
+   ```
+
+10. Create `notes.md` stub:
+    ```markdown
+    # Notes — <full-branch-name>
+    ```
+
+11. If beads is available, find or create the branch epic:
+    ```bash
+    bd search "<branch>" --status all 2>/dev/null
+    ```
+    - If an epic already matches, reuse its ID and update `beads-epic:` in `context.md`.
+    - If the work is substantial enough, create one: `bd create "<branch>" --type epic --label "branch:<branch>" --silent`
+    - For a single-ticket fix, skip the epic and let the ticket ID stand in for `beads-epic:`.
+
+12. Confirm:
+    ```
+    ✓ ~/.whisper/ initialized
+
+    Repo:  <repo-url>
+    Branch: <branch> → branches/<slug>/
+    Epic:  <id | none — will be created by /w link>
+    rules.md:     [created | exists]
+    env.md:       [created | exists]
+    worktree/env.md: [created | exists]
+
+    Run `/w link` after writing a plan.
+    ```

package/pi-package/skills/whisper/references/link.md

@@ -0,0 +1,70 @@
+# Link
+
+Attach a plan file to the workspace and create beads issues for each phase, as children of the branch epic. Run this after writing or generating a plan.
+
+This mode is self-contained — it does NOT require `create-plan` to have been used. The plan can come from anywhere: manually written, generated by any tool, or copied in.
+
+## Steps
+
+1. Run **check** first to confirm the slot exists.
+
+2. Get repo URL and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   context_path="$branch_dir/context.md"
+   plan_path="$branch_dir/plan.md"
+   ```
+
+3. Determine the plan file path:
+   - If the user provided a path (`/w link path/to/plan.md`): use that.
+   - Otherwise: use `plan.md`.
+   - If neither exists: tell the user to write a plan first and stop.
+
+4. If the source path is not `plan.md`, copy it in:
+   ```bash
+   cp <source-path> "$branch_dir/plan.md"
+   ```
+
+5. Read `plan.md` and extract phase headings.
+
+6. Ensure the branch epic exists:
+   - If `context.md`'s `beads-epic:` is already set, use it.
+   - If blank and the plan has more than one phase: create it.
+   - If blank and the plan is a single task: skip the epic.
+
+7. For each phase/task, create a beads issue as a child of the branch epic:
+   ```bash
+   bd create "<phase-title>" --type task --parent <epic-id>
+   ```
+
+8. Only if phases are genuinely sequential, chain dependencies:
+   ```bash
+   bd dep <id-N> --blocks <id-N+1>
+   ```
+
+9. Update `context.md` — set `beads-epic:` to the epic (or single-ticket) ID.
+
+10. **After each successful creation**, extract the `**Files / Systems:**` bullet list from the issue description and store it as structured metadata:
+    ```bash
+    bd update <id> --metadata '{"files": ["path/to/file1.py", "path/to/file2.py"]}'
+    ```
+    This enables automated file-conflict detection by concurrent agents. If the Files/Systems section is empty or contains only subsystem names without concrete paths, **stop and ask for specific file paths** — a ticket without concrete paths cannot participate in conflict detection.
+
+11. Confirm:
+    ```
+    Linked plan to workspace: branches/<slug>/
+    Epic: <epic-id> — <branch>
+    Created <n> child issues:
+      <id>  Phase 1: ...
+    ```
+
+### Relinking
+
+If `context.md` already has a `beads-epic:` set, ask before creating new children:
+```
+context.md already links epic <id> with <n> children.
+Add new phases as more children of the same epic? [Y/n]
+```

package/pi-package/skills/whisper/references/status.md

@@ -0,0 +1,49 @@
+# Status
+
+Show the state of the current workspace.
+
+## Steps
+
+1. Get repo URL and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   ```
+
+2. If `context.md` doesn't exist, delegate to **check** mode and stop.
+
+3. Read `context.md` and extract: repo, branch, path, beads-epic.
+
+4. Show `env.md` info:
+   ```bash
+   date -r ~/.whisper/repos/"${repo_url}"/env.md "+%Y-%m-%d %H:%M" 2>/dev/null
+   ```
+
+5. Show the branch epic's tree if beads is available:
+   ```bash
+   bd children <beads-epic> --pretty 2>/dev/null
+   ```
+
+6. Show plan status: is `plan.md` a stub or does it have real content?
+
+7. Show all active branch slots for this repo (most recently modified first):
+   ```bash
+   ls -t ~/.whisper/repos/"${repo_url}"/branches/ 2>/dev/null
+   ```
+
+### Output format
+
+```
+── Whisper: <repo> ──
+Branch:    <branch>  (branches/<slug>/)
+Plan:      [exists | stub]
+Epic:      <id> — <n> issues (<open> open)   [or: none linked yet]
+
+Active branch slots:
+  <ls output>
+
+Epic tree:
+  <bd children --pretty output, or "none">
+```

package/scripts/generate-pi-resources.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..");
+const manifestPath = path.join(repoRoot, "content", "manifest.json");
+const outRoot = path.join(repoRoot, "pi-package");
+const skillsOut = path.join(outRoot, "skills");
+const promptsOut = path.join(outRoot, "prompts");
+
+function escapeYamlDoubleQuoted(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function resetDir(dir) {
+  if (fs.existsSync(dir)) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      fs.rmSync(path.join(dir, entry.name), { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }
+  }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function generateSkill(prompt) {
+  const distilledPath = path.join(repoRoot, prompt.distilled);
+  const skillDir = path.join(skillsOut, prompt.name);
+  ensureDir(skillDir);
+
+  const frontmatter = [
+    "---",
+    `name: ${prompt.name}`,
+    `description: \"${escapeYamlDoubleQuoted(prompt.description || `Incitaciones prompt: ${prompt.name}`)}\"`,
+    "metadata:",
+    '  installed-from: "incitaciones"',
+    "---",
+    "",
+  ].join("\n");
+
+  fs.writeFileSync(path.join(skillDir, "SKILL.md"), frontmatter + readText(distilledPath), "utf8");
+
+  if (distilledPath.endsWith(`${path.sep}SKILL.md`)) {
+    const srcDir = path.dirname(distilledPath);
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+      if (entry.name === "SKILL.md") continue;
+      const src = path.join(srcDir, entry.name);
+      const dst = path.join(skillDir, entry.name);
+      if (entry.isDirectory()) {
+        fs.cpSync(src, dst, { recursive: true });
+      } else {
+        fs.copyFileSync(src, dst);
+      }
+    }
+  }
+}
+
+function generatePromptTemplate(prompt) {
+  const description = prompt.description || `Incitaciones prompt: ${prompt.name}`;
+  const template = [
+    "---",
+    `description: \"${escapeYamlDoubleQuoted(`Shortcut for the ${prompt.name} skill. ${description}`)}\"`,
+    "---",
+    "<!-- installed-from: incitaciones -->",
+    "",
+    `Use the installed \`${prompt.name}\` skill for this task.`,
+    "",
+    `If the skill is not automatically loaded, invoke \`/skill:${prompt.name}\` and follow it.`,
+    "",
+    "User context: $@",
+    "",
+  ].join("\n");
+
+  fs.writeFileSync(path.join(promptsOut, `${prompt.name}.md`), template, "utf8");
+}
+
+function main() {
+  const manifest = JSON.parse(readText(manifestPath));
+  resetDir(outRoot);
+  ensureDir(skillsOut);
+  ensureDir(promptsOut);
+
+  for (const prompt of manifest.prompts) {
+    generateSkill(prompt);
+    generatePromptTemplate(prompt);
+  }
+
+  const readme = [
+    "# Generated pi package resources",
+    "",
+    "This directory is generated by `node scripts/generate-pi-resources.mjs`.",
+    "The generated files are committed so `pi install .` works from a clean checkout.",
+    "Refresh them with `just generate-pi-resources` after changing distilled content or manifest entries.",
+    "Do not edit files here by hand.",
+    "",
+    "- `skills/` contains pi-compatible Agent Skills",
+    "- `prompts/` contains pi prompt templates",
+    "",
+    "## Install from npm",
+    "",
+    "```bash",
+    "pi install npm:incitaciones",
+    "```",
+    "",
+    "This package is published as [`incitaciones` on npm](https://www.npmjs.com/package/incitaciones).",
+    "",
+  ].join("\n");
+  fs.writeFileSync(path.join(outRoot, "README.md"), readme, "utf8");
+
+  console.log(`Generated pi resources for ${manifest.prompts.length} prompts in ${path.relative(repoRoot, outRoot)}/`);
+}
+
+main();

package/content/distilled/implement-documentation.md

@@ -1,68 +0,0 @@
-# Implement Documentation Topic
-
-Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL RULES
-
-1. ✅ **DO:** Establish context and prerequisites in the first two sentences (EPPO).
-2. ✅ **DO:** Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
-3. ✅ **DO:** Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
-4. ✅ **DO:** Provide a clear "fail-state" or troubleshooting section (Minimalism).
-5. ❌ **DO NOT:** Mix intents (e.g., no deep theory in a How-to guide). If theory is *required* for a task, use a **Note:** or **Deep Dive:** sidebar to maintain quadrant purity.
-6. ❌ **DO NOT:** Use "Next" or "Previous" as the only navigational cues (EPPO).
-
-## Implementation Workflow
-
-### Step 1: Quadrant Check
-
-Identify the Diátaxis quadrant and follow its rhetorical rules:
-- **Tutorial:** Action-oriented, safe environment. Use the **Martini Glass** narrative pattern: Author-driven stem (guided context) → Reader-driven bowl (open exploration).
-- **How-to:** Task-focused, assumes baseline competence, minimal theory.
-- **Reference:** Fact-based, scannable tables, no narrative filler.
-- **Explanation:** Theoretical, discusses "Why," maps concepts.
-
-### Step 2: EPPO Initialization
-
-Every topic must stand alone. Start with:
-- **Title:** Clear, task- or concept-focused.
-- **Context Block:** "This topic covers [X]. You should already understand [Y] and have [Z] installed."
-
-### Step 3: Information Mapping
-
-Structure the body content:
-- **Chunking:** Break large blocks into units of <7 items.
-- **Labeling:** Use headers that describe the *result* or *content* (e.g., "Configuring the API" not just "Configuration").
-- **Tables/Lists:** Convert complex comparisons or steps into visual structures.
-
-### Step 4: AI-First Polish
-
-- **Semantic Headers:** Ensure headers are descriptive for RAG indexing.
-- **Compressed Summary:** Provide a 1-2 sentence "tl;dr" at the top for LLM ingestion.
-
-## Template (How-to Guide)
-
-```markdown
-# [Task-Focused Title]
-
-**TL;DR:** [1-sentence summary for human/AI]
-
-## Context & Prerequisites
-This guide explains how to [Goal]. Before starting, ensure you have:
-- [Prerequisite 1]
-- [Prerequisite 2]
-
-## [Action Step 1: Specific Result]
-[Chunked instructions]
-
-## [Action Step 2: Specific Result]
-[Chunked instructions]
-
-## Troubleshooting: Common Fail-States
-| Symptom | Cause | Fix |
-| :--- | :--- | :--- |
-| [Error] | [Reason] | [Solution] |
-
-## Further Exploration
-- [Lateral Link 1] (Subject affinity)
-- [Lateral Link 2] (Subject affinity)
-```

package/content/distilled/research-documentation.md

@@ -1,79 +0,0 @@
-# Research Documentation Architecture
-
-Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL RULES
-
-1. ✅ **DO:** Categorize every document into exactly one Diátaxis quadrant.
-2. ✅ **DO:** Identify "Frankenbooks" (documents with mixed intent/quadrants).
-3. ✅ **DO:** Map the "Snowflake" progression from Core Assertion to granular topics.
-4. ✅ **DO:** Verify EPPO compliance (Does each page establish its own context?).
-5. ❌ **DO NOT:** Start writing content yet; focus on architecture and gaps.
-6. ❌ **DO NOT:** Suggest stylistic changes (focus on structural integrity).
-
-## Process
-
-### Step 1: Define the Scope
-
-[User will provide a path to a documentation directory or a project description.]
-- Identify the primary audience (Novice vs. Expert).
-- State the "Core Assertion" (The single-sentence value proposition).
-- **Legacy Conflict Resolution:** If existing documentation contains multiple, conflicting "hooks," identify the most impactful one or propose a synthesis for the new architecture.
-
-### Step 2: Audit Existing Content (if applicable)
-
-For each file in the directory, determine:
-- **Quadrant:** (Tutorial | How-to | Reference | Explanation).
-- **EPPO Status:** (Pass/Fail) Does it have standalone utility and context?
-- **Cognitive Load:** Are there "walls of words" or missing labels?
-
-### Step 3: Map the Snowflake Outline
-
-Expand the Core Assertion into a structural map:
-1. **Core Assertion:** [1 sentence]
-2. **Macro-Expansion:** [1 paragraph user journey]
-3. **Component List:** [The "characters" of the system]
-4. **Topic Matrix:** A list of proposed EPPO topics categorized by quadrant.
-
-### Step 4: Identify Gaps and Friction
-
-- **Quadrant Imbalance:** e.g., "Too much reference, not enough tutorials."
-- **Structural Plot-holes:** Where does the user journey break?
-- **AI-Readiness Gaps:** Missing `llms.txt`, poor semantic labeling.
-
-### Step 5: Final Research Report
-
-Output the audit/plan using the following template:
-
-```markdown
-# Documentation Research: [Project Name]
-
-## 1. Executive Summary & Core Assertion
-**Core Assertion:** [The one-sentence hook]
-**Status:** [Summary of current architecture health]
-
-## 2. Diátaxis Matrix
-| Quadrant | Existing Topics | Proposed/Missing Topics |
-| :--- | :--- | :--- |
-| **Tutorial** | | |
-| **How-to** | | |
-| **Reference** | | |
-| **Explanation** | | |
-
-## 3. Snowflake Structural Map
-- **Macro-Journey:** [Description]
-- **Key Components:** [List]
-
-## 4. EPPO & Cognitive Audit
-- **Frankenbooks Found:** [List of files with mixed intent]
-- **Context Gaps:** [Topics needing better orientation]
-
-## 5. AI-Readiness Assessment
-- [ ] `llms.txt` present?
-- [ ] Explicit semantic labeling for RAG?
-- [ ] MCP endpoints identified?
-
-## 6. Recommended Next Steps
-1. [Actionable structural change]
-2. [Actionable topic creation]
-```