incitaciones 0.8.0 → 0.10.0

package/README.md

@@ -7,7 +7,22 @@ A collection of reusable prompts and best practices for CLI LLM tools.
 
 ## Quick Install
 
-### Via npm / npx (recommended)
+### Via skills.sh (works with any agent)
+
+```bash
+# Browse & install interactively (pick individual skills):
+npx skills add incitaciones
+
+# Install everything:
+npx skills add incitaciones --skill '*' --all
+
+# Install only a specific skill:
+npx skills add incitaciones --skill commit
+```
+
+The skills.sh catalog (committed `skills/` directory) is generated from `content/manifest.json` — compat pointers are marked `metadata.internal: true` and hidden from discovery there.
+
+### Via npm / npx (pi + multi-tool installers)
 
 ```bash
 # Install as pi package (native skills, best UX):
@@ -89,6 +104,13 @@ After changing distilled content or manifest entries, you don't need to touch `p
 
 ### Publishing a new version
 
+Before publishing — and on every **model or provider change** — rerun the skill
+evals; a model upgrade can silently break an unchanged skill:
+
+```bash
+just skill-eval commit   # add more skills as fixtures land (scripts/skill-eval-fixtures/)
+```
+
 ```bash
 npm version patch   # bumps to 0.5.1, creates a git tag
 npm version minor   # bumps to 0.6.0
@@ -153,7 +175,7 @@ just search
 Everything lives in `content/` with descriptive filenames:
 
 - `prompt-*.md` - Reusable prompts (source)
-- `distilled/` - Optimized prompts for agent consumption (single file or multi-file)
+- `distilled/` - Optimized prompts for agent consumption (single file, multi-file, or router + references/ — see AGENTS.md "Distilled Formats")
 - `research-*.md` - Experiments and findings
 - `example-*.md` - Real-world examples
 - `template-*.md` - Templates for new content

package/content/distilled/codebase-cartography/references/report-template.md

@@ -12,10 +12,11 @@ Structure the final output by mode. All modes share the closing sections. Keep m
 
 ## Mode: macro
 
-1. **Module inventory** — table (module, path, responsibility, deps out, fan-in)
+1. **Module inventory** — table (module, path, responsibility, weight bar, deps out, fan-in)
 2. **Dependency matrix** — text DSM with ↑ marks for layer violations
 3. **Module graph** — Mermaid, edges labeled with counts
-4. Structural observations
+4. **Composition** — disk-reality breakdown by file kind (source / test / generated / vendored / config), excluded code included; distinct from the inventory weight column (analysis code, exclusions applied)
+5. Structural observations
 
 ## Mode: meso
 
@@ -65,7 +66,7 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 An explicit batch request ("generate all the reports", "map every module") is a user request — Zoom Discipline's offer-don't-dump rule applies to unprompted follow-ups only.
 
 - Enumerate targets from the module inventory. Confirm the list once when it exceeds 3 targets or the scope is ambiguous; proceed unless corrected.
-- One markdown per target in `docs/cartography/` — each the artifact of record for its target. For each, re-verify counts immediately before writing (Zoom Discipline).
+- One markdown per target in `docs/cartography/` — each the artifact of record for its target. For each, re-verify counts and re-confirm weight/composition shares immediately before writing — one consolidated pass per batch is fine (Zoom Discipline).
 - Include a health report only if the batch request names health/smells.
 - A target too large for one pass: skip it, mark it as "offered — too large for one pass" in the final summary and, when HTML export is part of the batch, in `index.html`. Do not stop the batch to ask.
 - Superseded artifacts from older exports (old-format HTML pages, render scripts): regenerate in place, recommend deleting the superseded script/pages, and never index stale-format files.

package/content/distilled/codebase-cartography/references/zoom-levels.md

@@ -13,13 +13,19 @@ Adapt import syntax to the language (see language rule below).
 2. Inter-module imports: scan import statements crossing module boundaries. Quoting-safe scan (works in POSIX shells), e.g. JS/TS: `rg 'from ["'"'"']' --type js --type ts` or simply `rg 'import|require'`; then filter by path.
 3. Count edges per pair of modules to get a weighted dependency list.
 4. Determine layering for violation flags: use the repo's declared layering (README/ARCHITECTURE/docs) if present; otherwise infer it from the majority dependency direction and label that inference in the report.
+5. **Weight & composition:** size each module by LOC (default) or file count (mixed-language repos, where LOC is not comparable across languages). Tool: `tokei` (apply the step-1 globs via `tokei -e ...`, or `cloc`); fallback: `rg --files -0 <exclusion globs> | xargs -0 wc -l`, summed per module. Two distinct metrics:
+   - **Weight** (inventory column) — analysis code only, same exclusions as all counts (step 1).
+   - **Composition** (report block) — disk reality: all code grouped by kind (source / test / generated / vendored / config), excluded code included. Classify by path/name conventions (`tests/`, `test_*.py`, `*_test.go`, `*.spec.ts` → test; step-1 exclusion-glob hits → generated/vendored; lockfiles, manifests, dotfiles → config). Works without modules too (flat/script repos): group by top-level directory or language.
+   If neither tool nor fallback works, degrade to file-count-only weight and note it in the report.
 
 **Render:**
 
 Module inventory table:
 
-| Module | Path | Responsibility (one line, from evidence) | Deps out → | Fan-in |
-| :---- | :---- | :---- | :---- | :---- |
+| Module | Path | Responsibility (one line, from evidence) | Weight | Deps out → | Fan-in |
+| :---- | :---- | :---- | :---- | :---- | :---- |
+
+Weight bar: 10-cell `▓/░` bar proportional to the module's share of total weight, rounded to nearest cell, minimum 1 filled cell when weight > 0, followed by an integer percentage — e.g. `▓▓▓▓▓▓▓░░░ 67%`. Weight flags candidate targets for deeper levels; size ≠ complexity (a big cohesive module can be cheaper to map than a small hotspot).
 
 Text dependency matrix (DSM-style). Rows depend on columns; mark `↑` for a dependency that skips a layer or points "backward" against the declared — or inferred (see collect step 4) — layering:
 
@@ -39,7 +45,7 @@ graph TD
   jobs --> core
 ```
 
-**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in).
+**Facts to surface:** layering violations (↑ marks), cycles, hub modules (highest fan-in/out), orphan modules (zero fan-in), bulk distribution (largest modules by weight; share of total).
 
 ## Meso — Module / Feature Wiring
 
@@ -97,3 +103,5 @@ RefundRequest{invoiceId, amount} → validated Amount → gateway response → L
 ```
 
 **Facts to surface:** where purity ends (first I/O hop), total hops, state mutated, error paths encountered (report; do not evaluate their quality).
+
+Decision record: macro maps encode scale as a proportional weight bar in the inventory table (treemap area-encoding, phronemophobic "Treemaps are awesome!") plus a Composition block, not as literal treemap graphics — the vendored Mermaid v9.4.3 has no treemap diagram (v11.5+ is ESM-only, CORS-blocked under `file://`) and an ASCII treemap is less diff-able than the bar column. (treemap evaluation, 2026-09-05)

package/content/distilled/context-guardian.md

@@ -12,9 +12,10 @@ You are the Gatekeeper of the Architecture. Before generating any code, always r
 **Directives**:
 1. FORBIDDEN: writing raw logic if a higher-level abstraction exists (no raw fetch() if useApi() exists, no inline error handling if handleError() exists, no raw CSS if a design system exists)
 2. Add `// Reusing: [Name] — avoids duplicating [what]` comments when using existing abstractions
-3. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead
+3. File Headers: every new source file opens with a `Purpose / Responsibilities / Rationale` header (see file-headers); when a change alters what a file does or why, update its Rationale in the same change — a stale header misleads. If the Purpose can't be stated in one sentence, the file mixes concerns: flag it for splitting instead of writing a vague header
+4. Refusal Protocol: if asked to violate architecture — STOP, explain the rule being violated, propose the resonant alternative instead
 
 **Output structure for every response**:
 1. Reuse Plan: "I will build X using [existing abstractions]. I need new code for [only what's new]."
 2. Code (with Reusing comments)
-3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed?
+3. Verification checklist: all abstractions reused? no raw logic where abstraction exists? style conventions followed? file headers present (new files) and current (changed files)?

package/content/distilled/diagnostician/SKILL.md

@@ -0,0 +1,32 @@
+# Diagnostician Router
+
+Advisory-only diagnostic evaluation of a codebase, product, or document. Each mode detects a family of pathologies and maps findings to named refactoring/remediation patterns. **Do not modify files in any mode — output findings and recommendations only.**
+
+## Modes
+
+| Question the user is asking | Mode | Read |
+|---|---|---|
+| Is it tangled? coupling, cohesion, cycles, God Objects | modularity-diagnostician | `references/modularity-diagnostician.md` |
+| Is change resisted? inheritance rigidity, OCP violations | rigidity-diagnostician | `references/rigidity-diagnostician.md` |
+| Is mutable state pathological? side-effect entanglement | mutability-diagnostician | `references/mutability-diagnostician.md` |
+| Can invalid states be represented? primitive obsession, boolean blindness | invalid-states-diagnostician | `references/invalid-states-diagnostician.md` |
+| Does it compose? type mismatches, missed endomorphisms, algebra gaps | composability-diagnostician | `references/composability-diagnostician.md` |
+| How does it fail? detection, classification, recovery, learning | error-handling-diagnostician | `references/error-handling-diagnostician.md` |
+| Why is Julia slow? type instability, allocation floods, dispatch | julia-performance-diagnostician | `references/julia-performance-diagnostician.md` |
+| Is the product usable? HEART, SPACE/DX Core 4, CLI/API heuristics, Diátaxis | ux-dx-evaluation-diagnostician | `references/ux-dx-evaluation-diagnostician/SKILL.md` |
+| Is the spec verifiable/buildable? | testability-implementability-evaluator | `references/testability-implementability-evaluator.md` |
+| Is this document true? factual errors, unsupported claims, provenance | verification-diagnostician | `references/verification-diagnostician.md` |
+| Is the specification complete/correct/coherent? (ISO 29148) | specification-evaluation-diagnostician | `references/specification-evaluation-diagnostician.md` |
+| Why did this fail? root cause analysis, method selection, corrective actions | rca-diagnostician | `references/rca-diagnostician/SKILL.md` |
+
+## Mode notes
+
+- The diagnostician modes are **mutually exclusive by design** — each SKILL.md opens with a GUARD naming its neighbors. Read the GUARD before running a diagnosis; redirect when the symptom belongs to another mode.
+- Formal-verification readiness (paradigm assessment, safety/liveness properties, toolchain scoping) is its own skill — `formal-verification-evaluator` — outside this router; redirect there when the question is about proof-readiness rather than build/test-readiness.
+- Multi-file modes (`rca-diagnostician`, `ux-dx-evaluation-diagnostician`) carry their templates in their own `references/` subdirectory.
+
+## Procedure
+
+1. Pick the mode whose *question* matches (not merely whose keyword matches).
+2. Read the referenced file; follow its INPUT → PROTOCOL pipeline and report template.
+3. Rank corrective actions by strength as the mode specifies; never auto-apply them.

package/content/distilled/{modularity-diagnostician.md → diagnostician/references/modularity-diagnostician.md}

@@ -23,6 +23,7 @@ Step 1 — Detect Modularity Signals: Read all files. Identify:
 - High Afferent Coupling (Medium): module depended upon by many consumers — alterations trigger widespread ripple effects
 - Temporal Coupling (Medium): files co-changing in commits despite no static dependency — reveals hidden dependencies (skip if no git/co-change data provided)
 - Missing Boundary (Medium): related functionality spread across modules with no clear owning package
+- Undescribable Module (Medium): a file's purpose cannot be stated in one sentence — the file-header Purpose is missing, stale, or forced to be vague (see `file-headers`). The header is the cohesion contract; needing three sentences means the module is doing three jobs
 Note file, line range, and description for each.
 
 Step 2 — Classify Modularity Scope: For each signal, assess:

package/content/distilled/doc-link-verifier/SKILL.md

@@ -93,90 +93,19 @@ Group results by source file so the user can see which docs are worst-hit.
 
 ### Step 4 — Contextual correctness (the hard part)
 
-A link can pass Step 3 (it resolves, the anchor exists) and still be wrong — pointing at an outdated version of a page, at the wrong section, at a page whose title/subject no longer matches what the surrounding prose promises. This is what the user means by "correct in context."
+A link can resolve cleanly and still be wrong: pointing at an outdated page, the wrong section, or a page whose subject no longer matches the surrounding prose.
 
-**Shallow check (default).** For each `ok` link, compare the link text (and a sentence of surrounding context) to the target's identifying label:
-- External link, deep mode was run: compare to `<title>` and H1.
-- Relative link to another repo file: compare to the file's first H1, or to the heading just under the fragment if one is present. You can read the file directly — this is cheap.
-- Anchor-only link: compare the link text to the heading itself.
+- **Shallow check (default):** compare link text plus surrounding context to the target's identifying label (title, H1, or heading at the anchor). Flag specific mismatches; don't flag generic link text — note it instead.
+- **Deep check (on request, or for suspicious cases):** fetch/read the target's actual content and ask whether the context's claim holds up.
+- Escalate shallow→deep when the shallow check flagged a specific mismatch, the context makes a specific technical claim, or the user asked for a thorough audit. Don't escalate for generic link text or huge link counts.
 
-Shallow check mismatches worth flagging:
-- Link text says "the API reference" but the target's title is "Installation Guide."
-- Link text says "see the v2 migration notes" but the target page is titled "v3 migration notes."
-- Link text references a specific concept ("rate limiting") and the target page is about something unrelated ("authentication").
-
-Shallow misses are usually false alarms when the link text is generic ("see here", "this page", "click here"). Don't flag those — instead, note in the report that generic link text makes contextual verification impossible and suggest more descriptive text if the user cares.
-
-**Deep check (on request, or for suspicious cases).** Fetch the target page's content and read it. For external links, this means re-running `check_links.py` with `--deep` to pull titles/headings, and for the most suspicious cases, using `web_fetch` yourself to read the full page. For relative links, just read the target file.
-
-Then ask: does the surrounding context's claim hold up when you look at what the target actually says?
-
-**Example — shallow pass, deep fail:**
-
-> "For rate limiting details, see the [API guide](https://example.com/api)."
-
-Shallow: link text "API guide", target title "API Guide" → match, passes.
-Deep: page is about endpoints and auth; there's no rate limiting section anywhere → contextual mismatch.
-
-**Example — deep pass:**
-
-> "See [issue #42](https://github.com/org/repo/issues/42) for the discussion of the memory leak."
-
-Deep: fetch the issue, confirm the title/body talk about a memory leak → context is correct.
-
-When to escalate from shallow to deep automatically:
-- The shallow check flagged a mismatch, but the link text is specific enough that it's worth verifying before reporting.
-- The surrounding context makes a specific technical claim ("as shown in X"), and the user has asked for a thorough audit.
-- The user explicitly asked for a deep check.
-
-When NOT to escalate:
-- The link text is generic ("here", "this", "docs").
-- The repo has thousands of external links (the network cost is too high; ask the user if they want to narrow the scope).
+Full criteria, examples (shallow-pass/deep-fail and deep-pass), and escalation rules: read `references/contextual-correctness.md`.
 
 ### Step 5 — Produce the report
 
-The report has a consistent structure so users can skim or drill in:
-
-```markdown
-# Link audit: <repo>
-
-## Summary
-- Scanned N files, found M links
-- ✅ ok: X · ⚠️ redirected: Y · ❌ broken: Z · ❓ anchor-missing: W · ⏭ skipped: V
-- Contextual mismatches flagged: K
-
-## Broken links (❌)
-Grouped by source file. For each:
-- File + line number
-- Link text and URL
-- What went wrong (HTTP status / "file not found" / etc.)
-- Suggested fix if one is obvious
-
-## Missing anchors (❓)
-For each:
-- File + line, link text, URL
-- Available headings in the target (from the check result)
-- Best-guess replacement
-
-## Redirects worth updating (⚠️)
-Only include notable ones — permanent URL changes, org renames, etc.
-Don't flood the report with trivial http→https redirects unless the user asked.
-
-## Contextual mismatches
-The judgment calls from Step 4. Each one shows:
-- The source line with context
-- The link
-- What the target actually contains
-- Why it's a mismatch
-- Suggested fix or "needs human review"
-
-## Generic link text
-Links whose text is too generic to verify contextually ("here", "this", "click here").
-Not a bug; a quality suggestion.
-```
+Use the fixed report structure (summary with ok/redirected/broken/anchor-missing/skipped counts, then Broken links, Missing anchors, Redirects worth updating, Contextual mismatches, Generic link text) so users can skim or drill in. The exact template: read `references/report-template.md`.
 
 Keep the report in a file (`link-audit.md` in the repo root, or wherever the user prefers) and **also** surface the top issues inline so the user sees them without opening the file.
-
 ### Step 6 — Fixes (opt-in, confirmation required)
 
 After presenting the report, offer to fix things. Never apply fixes without confirmation — users have strong opinions about their docs and some "broken" links are intentional (internal-only URLs, placeholder URLs in templates, etc.).

package/content/distilled/doc-link-verifier/references/contextual-correctness.md

@@ -0,0 +1,41 @@
+# Contextual correctness — full criteria
+
+A link can pass Step 3 (it resolves, the anchor exists) and still be wrong — pointing at an outdated version of a page, at the wrong section, at a page whose title/subject no longer matches what the surrounding prose promises. This is what the user means by "correct in context."
+
+**Shallow check (default).** For each `ok` link, compare the link text (and a sentence of surrounding context) to the target's identifying label:
+- External link, deep mode was run: compare to `<title>` and H1.
+- Relative link to another repo file: compare to the file's first H1, or to the heading just under the fragment if one is present. You can read the file directly — this is cheap.
+- Anchor-only link: compare the link text to the heading itself.
+
+Shallow check mismatches worth flagging:
+- Link text says "the API reference" but the target's title is "Installation Guide."
+- Link text says "see the v2 migration notes" but the target page is titled "v3 migration notes."
+- Link text references a specific concept ("rate limiting") and the target page is about something unrelated ("authentication").
+
+Shallow misses are usually false alarms when the link text is generic ("see here", "this page", "click here"). Don't flag those — instead, note in the report that generic link text makes contextual verification impossible and suggest more descriptive text if the user cares.
+
+**Deep check (on request, or for suspicious cases).** Fetch the target page's content and read it. For external links, this means re-running `check_links.py` with `--deep` to pull titles/headings, and for the most suspicious cases, using `web_fetch` yourself to read the full page. For relative links, just read the target file.
+
+Then ask: does the surrounding context's claim hold up when you look at what the target actually says?
+
+**Example — shallow pass, deep fail:**
+
+> "For rate limiting details, see the [API guide](https://example.com/api)."
+
+Shallow: link text "API guide", target title "API Guide" → match, passes.
+Deep: page is about endpoints and auth; there's no rate limiting section anywhere → contextual mismatch.
+
+**Example — deep pass:**
+
+> "See [issue #42](https://github.com/org/repo/issues/42) for the discussion of the memory leak."
+
+Deep: fetch the issue, confirm the title/body talk about a memory leak → context is correct.
+
+When to escalate from shallow to deep automatically:
+- The shallow check flagged a mismatch, but the link text is specific enough that it's worth verifying before reporting.
+- The surrounding context makes a specific technical claim ("as shown in X"), and the user has asked for a thorough audit.
+- The user explicitly asked for a deep check.
+
+When NOT to escalate:
+- The link text is generic ("here", "this", "docs").
+- The repo has thousands of external links (the network cost is too high; ask the user if they want to narrow the scope).

package/content/distilled/doc-link-verifier/references/report-template.md

@@ -0,0 +1,39 @@
+# Link audit report template
+
+```markdown
+# Link audit: <repo>
+
+## Summary
+- Scanned N files, found M links
+- ✅ ok: X · ⚠️ redirected: Y · ❌ broken: Z · ❓ anchor-missing: W · ⏭ skipped: V
+- Contextual mismatches flagged: K
+
+## Broken links (❌)
+Grouped by source file. For each:
+- File + line number
+- Link text and URL
+- What went wrong (HTTP status / "file not found" / etc.)
+- Suggested fix if one is obvious
+
+## Missing anchors (❓)
+For each:
+- File + line, link text, URL
+- Available headings in the target (from the check result)
+- Best-guess replacement
+
+## Redirects worth updating (⚠️)
+Only include notable ones — permanent URL changes, org renames, etc.
+Don't flood the report with trivial http→https redirects unless the user asked.
+
+## Contextual mismatches
+The judgment calls from Step 4. Each one shows:
+- The source line with context
+- The link
+- What the target actually contains
+- Why it's a mismatch
+- Suggested fix or "needs human review"
+
+## Generic link text
+Links whose text is too generic to verify contextually ("here", "this", "click here").
+Not a bug; a quality suggestion.
+```

package/content/distilled/documentation/SKILL.md

@@ -0,0 +1,22 @@
+# Documentation Router
+
+Route documentation work to the right mode, then read that mode's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| audit existing docs or plan a new documentation suite | research-documentation | `references/research-documentation/SKILL.md` |
+| write documentation using Diátaxis, Info Mapping, EPPO principles | implement-documentation | `references/implement-documentation/SKILL.md` |
+| review docs for cognitive scannability and AI-readiness | review-documentation | `references/review-documentation/SKILL.md` |
+
+## Selection rules
+
+- No docs or restructuring from scratch → **research-documentation** first; its report feeds implementation.
+- Writing or rewriting content → **implement-documentation**. Judging existing content quality → **review-documentation**.
+- Broken links or link-text/target mismatches are the complaint → use the `doc-link-verifier` skill instead; this router is about architecture and content quality.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its checklists, templates, and report formats.

package/content/distilled/file-headers.md

@@ -0,0 +1,26 @@
+<!-- Full version: content/prompt-system-file-headers.md -->
+You enforce file-header documentation on source code. Every source file must be self-describing: an agent opening any file must learn what it does and why it exists without reading the implementation or hunting for context.
+
+**HEADER FORMAT** (adapt the comment syntax to the language — `#`, `//`, `--`, `"""docstring"""`, or a top doc comment):
+
+```
+# Purpose: <one sentence — what this file does and for whom>
+# Responsibilities:
+# - <bullet 1 — the cohesion contract; one concern per bullet>
+# - <bullet N>
+# Rationale: <latest design decision and why, with issue/PR link>
+#   <earlier rationale entries belong in the issue tracker / git history>
+```
+
+**Rules:**
+1. Every NEW source file opens with a complete header before any logic.
+2. When a modification changes what a file does or why, update the header in the same change — a stale header is worse than none. Do not touch the header for behavior-preserving edits.
+3. Purpose is one sentence. If you cannot state it in one sentence, the file likely mixes concerns — flag it for splitting (see modularity-diagnostician) rather than writing a vague header.
+4. Rationale keeps only the latest entry. History lives in the issue tracker and git, not the file.
+5. Exclusions: generated files, vendored code, config, lockfiles, docs, and build artifacts get no header.
+
+**Scope — "source file" means:** files containing logic or defining structure written by this project (modules, classes, scripts, routes, components, tests). Not applicable to READMEs, org notes, or one-liner re-exports.
+
+**Audit:** to find missing headers: `grep -rLE "(Purpose:|@purpose)" --include=<source-extensions> .` excluding vendored/generated paths. Every hit is a gap.
+
+**Output:** when adding or updating headers, show file → header block. When a file fails Rule 3 (undescribable), report it as a modularity finding with the offending concerns listed.

package/content/distilled/grill-me.md

@@ -9,12 +9,12 @@ You are an exacting design interviewer. Interview the user relentlessly about a
 1. Walk each branch of the design tree.
 2. Resolve dependencies between decisions one by one.
 3. For every question, provide your recommended answer.
-4. Ask questions one at a time.
-5. If a question can be answered by exploring the codebase, inspect the codebase instead of asking.
+4. Ask questions **one at a time**. Exactly ONE question per turn — bundling several questions into a single turn violates this skill. If several decisions are queued, pick the highest-leverage one, answer the rest with your recommendation, and note they are queued for later turns.
+5. If a question can be answered by exploring the codebase, inspect the codebase instead of asking — in simulations, state which path you would inspect and what you would look for rather than asking the user.
 6. Continue until major branches are resolved or explicitly marked open.
 
 **OUTPUT PER TURN**
-- **Question:** one focused question
+- **Question:** exactly one focused question (never a bundle)
 - **Recommended answer:** best current recommendation
 - **Why this matters:** brief rationale
 

package/content/distilled/issues/SKILL.md

@@ -0,0 +1,21 @@
+# Issues Router
+
+Route issue-tracking work to the right mode, then read that mode's instructions before acting. Both modes assume a tracker CLI (beads `bd` by default) — check the project's AGENTS.md for the tracker in use.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| turn an implementation plan into trackable issues | create-issues | `references/create-issues/SKILL.md` |
+| review existing issues for completeness, dependencies, executability | issue-review | `references/issue-review/SKILL.md` |
+
+## Selection rules
+
+- Plan approved and needs to become work items → **create-issues**.
+- Issues exist and someone asks "are these ready/good/covered?" → **issue-review** (multi-pass: clarity, scope, dependencies, alignment, executability).
+- Creating issues from a plan that has not been reviewed? Suggest a plan review first.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its templates, pass structure, and output format.

package/content/distilled/{create-issues → issues/references/create-issues}/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.3.0, status: verified -->
+<!-- skill: create-issues, version: 1.4.1, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -26,8 +26,10 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
      - **AFK** — can be implemented and merged without human intervention.
      - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
    - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
+   - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer.
 
 4. **Review the proposed breakdown with the user:**
+   - Re-run the title lint on every drafted title; merge any layer-named ticket into its outcome slice before presenting.
    - Present a numbered list before creating anything.
    - For each slice include:
      - **Title**
@@ -45,6 +47,7 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
      - end-to-end behavior description
      - concrete file paths or subsystems when knowable
      - binary acceptance criteria
+     - a **file-header criterion** when the slice creates source files or changes a file's contract: new files open with `Purpose / Responsibilities / Rationale`; contract-changing edits update Rationale (see `file-headers`)
      - a **Verifiable Value Claim** where measurable: quantified **Must** gate (unit + number, no adjectives), a runnable **Meter** command, the measured **Baseline**, and the **regression suite** that must keep passing
      - **anti-goals** whenever the ticket touches tests, lockfiles, or public interfaces (prohibit test-assertion edits, dependency additions, API breaks)
      - explicit blocked-by field
@@ -83,6 +86,7 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Workflow integrity:** TDD and Tidy First language is mandatory in every implementation issue.
 - **No guessed IDs:** capture identifiers from actual command output.
 - **Quantify the gate:** every measurable acceptance criterion is a number with a unit, backed by a runnable Meter command.
+- **Self-describing files:** tickets that create source files or change a file's contract carry the file-header criterion (see `file-headers`).
 - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
 - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
 - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.

package/content/distilled/{create-issues → issues/references/create-issues}/references/templates.md

@@ -43,6 +43,7 @@ Ref: [Link to plan/spec file and section]
 - [ ] [Binary, observable criterion 1]
 - [ ] [Binary, observable criterion 2]
 - [ ] [Automated tests cover the slice end-to-end]
+- [ ] [When the slice creates source files or changes a file's contract: file-header criterion — new files carry Purpose/Responsibilities/Rationale; changed files update Rationale (see `file-headers`)]
 
 ## Blocked by
 

package/content/distilled/{issue-review → issues/references/issue-review}/SKILL.md

@@ -28,6 +28,7 @@ Treat the best issue sets as:
 - minimal but sufficient dependency graphs
 - explicit about AFK vs HITL work
 - traceable back to stories, plans, or specs
+- self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent
 - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness
 
 ## Rules

package/content/distilled/{issue-review → issues/references/issue-review}/references/pass-5-executability.md

@@ -4,6 +4,7 @@ Focus on:
 - Can another developer or agent pick this up immediately?
 - Are verification steps concrete and end-to-end?
 - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command?
+- Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)?
 - Are priorities and labels sensible?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
@@ -15,6 +16,7 @@ Watch for:
 - Qualitative acceptance criteria with no unit or threshold ("fast", "robust", "clean") — a Scale/Meter is missing
 - A Meter command that cannot run at the ticket's `base_commit` (stale claim) or that no fresh agent could execute verbatim
 - Missing anti-goals on tickets touching tests, lockfiles, or public interfaces (reward-hacking surface: nothing stops gaming the gate)
+- Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent
 - No regression suite named (pass-to-pass coverage unspecified)
 - HITL work masquerading as AFK
 - Tickets that cannot be closed without information from another issue not listed as a blocker

package/content/distilled/planning/SKILL.md

@@ -0,0 +1,23 @@
+# Planning Router
+
+Route planning work to the right mode, then read that mode's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| design a phased implementation plan (TDD-oriented) from a goal | create-plan | `references/create-plan/SKILL.md` |
+| execute an existing plan phase by phase | implement-plan | `references/implement-plan/SKILL.md` |
+| review an implementation plan for gaps, risks, sequencing | plan-review | `references/plan-review/SKILL.md` |
+| refine an existing plan from feedback or new constraints | iterate-plan | `references/iterate-plan/SKILL.md` |
+
+## Selection rules
+
+- No plan exists yet → **create-plan**. Plan exists and work is approved → **implement-plan**.
+- Plan exists but is under critique → **plan-review**; under revision → **iterate-plan**. Review first when feedback is vague, iterate when it is specific.
+- These modes chain: create-plan → plan-review → iterate-plan → implement-plan.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its templates and verification steps.

package/{pi-package/skills → content/distilled/planning/references}/implement-plan/SKILL.md

@@ -1,9 +1,3 @@
----
-name: implement-plan
-description: "Execute implementation plans phase by phase"
-metadata:
-  installed-from: "incitaciones"
----
 # Implement Plan
 
 Implement an approved plan using Red, Green, Refactor.
@@ -17,6 +11,7 @@ Implement an approved plan using Red, Green, Refactor.
    - Implement the minimum code to pass.
    - Refactor while keeping tests green.
    - Run the success criteria checks.
+   - Check file headers: new source files open with Purpose/Responsibilities/Rationale; files whose contract changed have a current Rationale (see `file-headers`).
    - Update the plan with progress.
 4. Use `references/verification-template.md` when reporting phase completion.
 5. Use `references/common-situations.md` when the plan and reality diverge.
@@ -25,5 +20,6 @@ Implement an approved plan using Red, Green, Refactor.
 
 - Never skip the red phase.
 - Complete one phase at a time.
+- Review file headers before declaring a phase complete: new files must carry them, and contract-changing edits must leave the Rationale current (see `file-headers`).
 - Do not blindly follow an outdated plan if the codebase contradicts it.
 - Wait for user confirmation before proceeding to the next phase.

package/{pi-package/skills → content/distilled/planning/references}/implement-plan/references/verification-template.md

@@ -5,6 +5,7 @@ Automated verification:
 - [x] All tests pass
 - [x] Type checking passes
 - [x] Build succeeds
+- [x] File headers current: new files carry Purpose/Responsibilities/Rationale; changed files updated Rationale (see `file-headers`)
 
 Manual verification needed:
 - [ ] [Manual step 1]

package/content/distilled/pointers/close.md

@@ -0,0 +1,7 @@
+# Moved: close
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/close` no more: invoke `/skill:session` and follow its mode table — this task is the **close** mode, which reads `references/close/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/create-handoff.md

@@ -0,0 +1,7 @@
+# Moved: create-handoff
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/create-handoff` no more: invoke `/skill:session` and follow its mode table — this task is the **create-handoff** mode, which reads `references/create-handoff/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/create-issues.md

@@ -0,0 +1,7 @@
+# Moved: create-issues
+
+This skill was consolidated into the **issues** skill (router + references/ layout).
+
+Use `/create-issues` no more: invoke `/skill:issues` and follow its mode table — this task is the **create-issues** mode, which reads `references/create-issues/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:issues`.

package/content/distilled/pointers/issue-review.md

@@ -0,0 +1,7 @@
+# Moved: issue-review
+
+This skill was consolidated into the **issues** skill (router + references/ layout).
+
+Use `/issue-review` no more: invoke `/skill:issues` and follow its mode table — this task is the **issue-review** mode, which reads `references/issue-review/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:issues`.

package/content/distilled/pointers/next.md

@@ -0,0 +1,7 @@
+# Moved: next
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/next` no more: invoke `/skill:session` and follow its mode table — this task is the **next** mode, which reads `references/next/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/park.md

@@ -0,0 +1,7 @@
+# Moved: park
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/park` no more: invoke `/skill:session` and follow its mode table — this task is the **park** mode, which reads `references/park/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.