incitaciones 0.2.0 → 0.3.1

package/README.md

@@ -1,5 +1,8 @@
 # Incitaciones 🤖
 
+[![npm](https://img.shields.io/npm/v/incitaciones)](https://www.npmjs.com/package/incitaciones)
+[![Publish to npm](https://github.com/charly-vibes/incitaciones/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/charly-vibes/incitaciones/actions/workflows/npm-publish.yml)
+
 A collection of reusable prompts and best practices for CLI LLM tools.
 
 ## Quick Install
@@ -87,6 +90,51 @@ The repository includes checked-in pi package resources under `pi-package/`, and
 
 After changing distilled content or manifest entries, run `just generate-pi-resources` and commit the updated `pi-package/` files.
 
+### Publishing a new version
+
+```bash
+npm version patch   # bumps to 0.2.1, creates a git tag
+npm version minor   # bumps to 0.3.0
+npm version major   # bumps to 1.0.0
+
+git push --tags     # triggers CI → auto-publishes to npm
+```
+
+CI workflow: `.github/workflows/npm-publish.yml` — runs on `v*` tags, generates pi resources, then publishes.
+
+## Top 10 Most Used Skills
+
+Based on analysis of 621 pi sessions across 43 repositories:
+
+| Skill | Invocations | Repos | What it does |
+|-------|:-----------:|:-----:|-------------|
+| **commit** | 513 | 41 | Create well-structured, atomic git commits with clear intent |
+| **rule-of-5-universal** | 254 | 35 | 5-stage review for any artifact (Steve Yegge's method) |
+| **tdd** | 168 | 28 | Test-driven development workflow |
+| **issue-review** | 158 | 31 | Review issues for completeness and dependencies |
+| **debug** | 94 | 27 | 7-step diagnostic workflow for debugging issues |
+| **create-issues** | 44 | 19 | Generate trackable issues from implementation plans |
+| **create-handoff** | 31 | 10 | Generate context documents for session continuity |
+| **grill-me** | 28 | 12 | Interview the user relentlessly about a plan or design |
+| **doc-link-verifier** | 27 | 9 | Audit documentation for broken links |
+| **review-documentation** | 27 | 9 | Review docs for cognitive scannability and AI-readiness |
+
+## Session Lifecycle & Knowledge Management
+
+Workflow skills that form a complete session lifecycle with persistent operational knowledge:
+
+| Skill | When | What it does |
+|-------|------|-------------|
+| **whisper** | Start of project/branch | Manage `~/.whisper/` — global, tiered knowledge directory (init, check, status, link, decommission) |
+| **next** | Quick context switch | Rapid snapshot to `~/.whisper/` — no git, no tickets, just stash |
+| **park** | Thorough context switch | Log to journal, release ticket claims, record to beads epic |
+| **close** | End of day | Log to journal, route knowledge to `~/.whisper/`, commit, clear |
+| **renew** | Start of session | Load journal + whisper + beads context, claim tickets with file conflict detection |
+
+Uses `$JOURNAL_PATH` (default `~/dev/status`) for the daily log. See [`content/references-whisper-workflow.md`](content/references-whisper-workflow.md) for the full reference.
+
+Full analysis: [`content/research-finding-skill-usage-analysis.md`](content/research-finding-skill-usage-analysis.md)
+
 ## Quick Start
 
 ```bash
@@ -113,6 +161,15 @@ Everything lives in `content/` with descriptive filenames:
 - `example-*.md` - Real-world examples
 - `template-*.md` - Templates for new content
 
+Key infrastructure files:
+
+- `package.json` — npm package with `pi` manifest and `bin` entry for npx CLI
+- `scripts/cli.mjs` — npx CLI entry point (`npx incitaciones install` / `list` / `info`)
+- `scripts/generate-pi-resources.mjs` — generates `pi-package/` from manifest
+- `pi-package/` — generated pi-compatible skills and prompt templates (gitignored)
+- `.github/workflows/npm-publish.yml` — CI: auto-publishes to npm on `v*` tags
+- `.github/workflows/pages.yml` — CI: deploys GitHub Pages site
+
 See [AGENTS.md](AGENTS.md) for detailed structure and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Commands

package/content/distilled/close/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: close
+description: "End-of-session wrap-up. Summarizes what was done, logs it to the daily journal, commits, pushes, and clears context. Trigger when the user says '/close', 'close session', or 'wrap up session'."
+tools: Read, Write, Edit, Glob, Bash
+---
+
+# Close Session
+
+End the current session: log what was done, update tasks, route durable knowledge to `~/.whisper/`, commit and push, clear context.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. The log subdirectory defaults to `log/`; set `$JOURNAL_LOG_SUBDIR` to override (e.g. `areas/log` for the JORNAL layout).
+
+## Steps
+
+1. Pull the journal repo:
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
+   cd "$JOURNAL" && git pull
+   ```
+
+2. Get today's date and time (`date +%Y-%m-%d`, `date +%H:%M`).
+   Derive the log path: `$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`
+
+3. If the log file does not exist, create it with the daily log template.
+
+4. Review the full conversation history and write a concise session summary covering:
+   - What was worked on (key topics, files, repos)
+   - Decisions made
+   - Tasks completed or created
+   - Any unresolved items or next steps
+
+5. Append the summary to the `## Log` section of today's daily log:
+   ```
+   ### Session:HH:MM (<context>)
+   - bullet point summary entries
+   - **Next:** what to pick up next time (if applicable)
+   ```
+
+6. Update project/area files if tasks were completed or created:
+   - Mark completed tasks `[x]`
+   - Add new tasks as `[ ]`
+   - Add/update `[~]` waiting items
+   - Update `## Notes` with decisions
+
+7. If any tasks or follow-ups came up that aren't in a project/area, add them to `inbox.md`.
+
+8. **Route durable knowledge to `~/.whisper/`.** Scan the session for anything worth keeping and route by scope (skip this step entirely if nothing durable was learned):
+   - **Branch-specific finding** → `bd note <beads-epic>` or `~/.whisper/repos/<repo>/branches/<slug>/notes.md`
+   - **Repo-wide infra fact** → `~/.whisper/repos/<repo>/env.md`
+   - **Universal agent behavior rule** → `bd remember` or `~/.whisper/rules.md`
+   - **Worktree setup fact** → `~/.whisper/repos/<repo>/worktrees/<name>/env.md`
+   - **No secrets anywhere:** never write tokens, keys, or PII
+   - **Extend, don't duplicate:** append to existing notes rather than creating new ones
+
+9. Commit and push. Stage only the files this session touched, explicitly by name:
+   ```bash
+   cd "$JOURNAL" && git add <log-file> [<files>] && git commit -m "log: YYYY-MM-DD session notes" && git push
+   ```
+
+10. As the very last step, run `/clear` to reset the conversation context.
+
+## Rules
+
+- Do NOT ask the user any questions. Summarize automatically from conversation context.
+- Keep the summary concise — bullet points, not paragraphs.
+- If today's log already has content, append to it; never overwrite existing entries.
+- Always pull before reading and push after committing.

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

@@ -54,6 +54,16 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Apply tracker labels such as `needs-triage` when the project uses them.
    - Wire dependencies using actual captured identifiers or explicit body references.
    - Verify each creation step succeeded before continuing.
+   - **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 (see `renew` skill
+     **Claiming work** section). If the Files/Systems section is empty or contains only
+     subsystem names without concrete paths, **stop and ask the user for specific file paths
+     before publishing the ticket** — a ticket without concrete paths cannot participate in
+     conflict detection and is incomplete.
 
 7. **Final report:**
    - Summarize the approved slice set, created issues, labels, and dependency links.

package/content/distilled/implement-documentation/SKILL.md

@@ -0,0 +1,29 @@
+# Implement Documentation Topic
+
+Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
+
+## Core Rules
+
+- Establish context and prerequisites in the first two sentences (EPPO).
+- Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
+- Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
+- Provide a clear "fail-state" or troubleshooting section (Minimalism).
+- Do not mix intents: no deep theory in a How-to. If theory is required, use a Note or Deep Dive sidebar to maintain quadrant purity.
+- Do not use "Next" or "Previous" as the only navigational cues (EPPO).
+
+## Procedure
+
+1. Quadrant check: identify the Diátaxis quadrant and follow its rhetorical rules. Use `references/templates.md` for the matching template (Tutorial, How-to, Reference, or Explanation). Use `references/anti-patterns.md` to avoid common failures for that quadrant.
+2. EPPO initialization: every topic must stand alone. Start with a clear task- or concept-focused title and a context block ("This topic covers [X]. You should already understand [Y] and have [Z] installed.").
+3. Information mapping: chunk the body into units under 7 items; label headers by result or content (e.g., "Configuring the API" not "Configuration"); convert complex comparisons or steps into tables and lists.
+4. AI-first polish: ensure headers are descriptive for RAG indexing and provide a 1-2 sentence TL;DR at the top for LLM ingestion.
+5. If setting up a new docs site or choosing tooling, use `references/tooling-comparison.md` for platform selection and `references/versioning.md` for versioning and changelog strategy. For a full Diátaxis rollout, use `references/diataxis-implementation.md`.
+
+## Rules
+
+- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.
+
+## Related Skills
+
+- `research-documentation` — audit before writing.
+- `review-documentation` — review after writing.

package/content/distilled/implement-documentation/references/anti-patterns.md

@@ -0,0 +1,35 @@
+# Documentation Anti-Patterns
+
+Avoid these during Step 1 (quadrant check) and throughout writing. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, Common Mistakes and Anti-Patterns).
+
+## Leading with explanation instead of action
+
+The engineer's impulse is to explain how a system works before showing how to use it. This is backwards for most users. Quickstart then how-to then reference is the ramp-up order. Fix: in Tutorials and How-tos, lead with a runnable result; move "how it works" to Explanation.
+
+## One stream of text serving as THE DOCS
+
+A single document trying to teach beginners, guide intermediate users, and serve as expert reference serves none of them. Fix: split by Diátaxis quadrant; each page has one intent.
+
+## FAQ lists as an anti-pattern
+
+An FAQ is "the box in the garage where you put things when you can't be bothered to put them in the right place." If information is in the right Diátaxis quadrant, it does not need repeating in an FAQ. Fix: place each answer where it belongs; delete the FAQ or keep only genuinely miscellaneous items.
+
+## The curse of knowledge
+
+Experts forget what it was like not to know. They skip "obvious" steps, use undefined jargon, assume context beginners lack. Fix: in Tutorials, state every prerequisite; define jargon on first use; have a non-expert read it.
+
+## Stale documentation
+
+Docs not embedded in the development workflow drift from the code. Incorrect docs are worse than missing docs — they waste time and erode trust. Fix: docs-as-code, docs-updated checkboxes in PRs, "you touch it, you document it."
+
+## Knowledge silos
+
+Scattered docs across wikis, READMEs, Confluence, Notion create a fragmented experience where users cannot find things and contributors do not know where to put new content. Fix: one canonical location, ideally in the same repo as the code.
+
+## Partial coverage
+
+Documenting some but not all of a feature or API creates a false sense of completeness — users assume the undocumented part does not exist or work. Fix: cover a concept fully or not at all; use the completeness checklist (in the `research-documentation` skill's `references/checklist.md`).
+
+## Mixed-intent "Frankenbooks"
+
+A page that starts as a tutorial, becomes reference, and ends as explanation. Fix: split into three focused pages; each keeps quadrant purity. Use a Note or Deep Dive sidebar only when a sliver of theory is required inside a task page.

package/content/distilled/implement-documentation/references/diataxis-implementation.md

@@ -0,0 +1,31 @@
+# Diátaxis Implementation Guide
+
+Six-step rollout for adopting Diátaxis on an existing or new documentation set. Use in Step 5 when the task is a full architecture rollout rather than a single topic. The Diátaxis framework theory is canonical in `content/research-documentation-frameworks.md`; these implementation steps are sourced from `content/research-finding-library-docs-best-practices.md` (Section 3, How to Implement Diátaxis in Practice).
+
+## Step 1: Audit existing documentation
+
+Catalog every existing document and classify it as Tutorial, How-to, Reference, or Explanation. The audit typically reveals that most docs are reference, with gaps in tutorials and explanation. (Use the `research-documentation` skill for this.)
+
+## Step 2: Create a directory structure
+
+Create four directories or sections: `tutorials/`, `how-to/` (or `guides/`), `reference/`, and `explanation/`. Apply title conventions per type: Explanation titles use "Understanding / Dive into / Introduction to..."; How-to titles start with "How to..."; Tutorial titles use "Getting started with...".
+
+## Step 3: Assign content types and split mixed documents
+
+Long mixed-topic documents become multiple short, focused documents. A document that is tutorial then reference then explanation becomes three separate documents, each in its quadrant directory.
+
+## Step 4: Establish contribution guidelines
+
+Document the framework for contributors so new docs land in the right place from the start. Without guidelines the four-directory structure fills with misclassified content. Keep the guidelines short: one sentence per quadrant on what belongs there.
+
+## Step 5: Integrate with the development workflow
+
+Add architecture specs to Reference alongside code changes. Add technical decision logs to Explanation during feature development. Docs-updated checkboxes in PR templates. This integration is what keeps docs current.
+
+## Step 6: Use Diátaxis as an AI prompt template
+
+The clear information patterns make effective AI prompt templates: ask a model to sort unstructured content into the four patterns to accelerate a first draft, then review and refine. (See `templates.md` for the per-quadrant output shapes.)
+
+## Critiques to keep in mind
+
+Diátaxis is a guide, not dogma. Forcing every artifact into four rigid buckets produces awkward docs. The terms overlap (tutorial vs. how-to needs editorial judgment). The framework does not address content reuse (DITA's conref may suit enterprise multi-output needs) nor finding aids. For early-stage projects, a single compelling quick start may suffice before the full suite.

package/content/distilled/implement-documentation/references/templates.md

@@ -0,0 +1,115 @@
+# Diátaxis Templates
+
+One template per quadrant. Match the template to the quadrant identified in Step 1. The canonical theory is `content/research-documentation-frameworks.md`.
+
+## Tutorial (learning-oriented, beginners)
+
+Goal: build competency through a guided, safe experience. Show, do not lecture.
+
+```markdown
+# [Getting Started with X]
+
+**TL;DR:** [1-sentence outcome for human/AI]
+
+## What You Will Learn
+By the end you will have [concrete result]. No prior knowledge of [X] is assumed.
+
+## Prerequisites
+- [Prerequisite 1]
+- [Prerequisite 2]
+
+## Step 1: [Specific Result]
+[Chunked, do-this-now instructions. Each step yields a visible result.]
+
+## Step 2: [Specific Result]
+[Chunked instructions.]
+
+## Recap & Next Steps
+You built [X]. Next, try [lateral link 1] or [lateral link 2].
+```
+
+## How-to (task-oriented, assumes baseline competence)
+
+Goal: answer a specific question directly. Minimal theory.
+
+```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)
+```
+
+## Reference (information-oriented, experienced users)
+
+Goal: fast, accurate facts. Scannable tables, no narrative filler.
+
+```markdown
+# [X] Reference
+
+**TL;DR:** [1-sentence summary for human/AI]
+
+## [Function/Endpoint/Class Name]
+
+**Signature:** `signature`
+
+**Parameters:**
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| [name] | [type] | yes/no | [description] |
+
+**Returns:** [type and meaning]
+
+**Errors:**
+| Code | Meaning | Remediation |
+| :--- | :--- | :--- |
+| [code] | [meaning] | [fix] |
+
+**Example:**
+[Minimal, complete, runnable example]
+```
+
+## Explanation (understanding-oriented, the "why")
+
+Goal: deepen knowledge; no specific task. Discussion, design rationale, trade-offs.
+
+```markdown
+# [Understanding X]
+
+**TL;DR:** [1-sentence summary for human/AI]
+
+## Why [X] Exists This Way
+[Design rationale and history. No steps.]
+
+## Key Concepts
+- [Concept 1]: [definition and why it matters]
+- [Concept 2]: [definition and how it relates to Concept 1]
+
+## Trade-offs
+| Approach | Pro | Con |
+| :--- | :--- | :--- |
+| [A] | [pro] | [con] |
+| [B] | [pro] | [con] |
+
+## Further Exploration
+- [Lateral Link 1] (Subject affinity)
+- [Lateral Link 2] (Subject affinity)
+```

package/content/distilled/implement-documentation/references/tooling-comparison.md

@@ -0,0 +1,46 @@
+# Tooling Comparison & Docs-as-Code
+
+Use in Step 5 when choosing a platform or setting up docs infrastructure. Platform selection is an implementation decision, not an audit finding. Source: `content/research-finding-library-docs-best-practices.md` (Section 6, Modern Tooling and Infrastructure).
+
+## Platform comparison
+
+| Platform | Best For | Stack | Key Strength |
+| :--- | :--- | :--- | :--- |
+| Docusaurus | Complex OSS docs, versioning | React/JS | Ecosystem, versioning, MDX |
+| MkDocs (Material) | Python projects, simple setup | Python | Simplicity, polished theme |
+| Sphinx | Python API reference | Python | Autodoc, multiple outputs |
+| Read the Docs | OSS hosting, versioning | Agnostic | Free hosting, versioning |
+| GitBook | Team knowledge bases | Agnostic | Editing UX, AI search |
+| Mintlify | API docs, dev portals | Agnostic | Design, AI search, OpenAPI |
+| Starlight | Performance-critical docs | Astro | Performance, accessibility |
+| Nextra | Custom Next.js sites | React/Next.js | Customization, React components |
+
+## How to choose
+
+- Python ecosystem or simplicity: MkDocs / Sphinx.
+- API reference that must stay synced to code: Sphinx autodoc, mkdocstrings, or TypeDoc.
+- API docs with interactive playground: Mintlify.
+- Complex OSS docs with versioning and i18n: Docusaurus.
+- Performance and built-in accessibility: Starlight.
+- Free open-source hosting with versioning: Read the Docs.
+
+## Docs-as-code workflow
+
+Write docs in plain text (Markdown/AsciiDoc/reST), store in Git, review through pull requests, publish through CI/CD. Core practices:
+
+- Store docs in the same repository as the code.
+- Write in plain text (Markdown dominates for developer docs).
+- Review all doc changes through the same PR process as code.
+- Automate builds and deployments via CI/CD (GitHub Actions, GitLab CI).
+- Enforce quality through automation: Vale, markdownlint, link checkers (htmlproofer, lychee), spell checkers on every PR.
+- Generate API reference from OpenAPI/Swagger to keep it synchronized.
+
+## Specification-driven API docs
+
+- **OpenAPI** is the standard for REST APIs (YAML/JSON). Use it to auto-generate interactive reference (Swagger UI, Redoc, Stoplight Elements), client SDKs, and mock servers, and to power AI agent tool manifests.
+- **AsyncAPI** extends the approach to event-driven APIs (WebSockets, Kafka, MQTT).
+- Prefer a **design-first** approach: write the spec before the code. This enables early collaboration, immediate mock servers, and ensures docs are never an afterthought.
+
+## Interactive documentation
+
+Place the interactive element directly adjacent to the relevant docs, not on a separate playground page. Live code playgrounds (CodeSandbox, StackBlitz), interactive API explorers (Swagger UI, Mintlify), and embedded REPLs reduce time-to-first-success.

package/content/distilled/implement-documentation/references/versioning.md

@@ -0,0 +1,31 @@
+# Versioning & Changelog Strategy
+
+Use in Step 5 when setting up versioned documentation. Source: `content/research-finding-library-docs-best-practices.md` (Section 2, Versioned Documentation Strategies).
+
+## Version-tagged documentation
+
+Each major release should have a corresponding docs version. Tools like Read the Docs, Docusaurus, and Sphinx provide built-in versioned docs so users can select the version matching their installed software.
+
+## Version selector in the UI
+
+A prominent version selector in navigation lets users switch versions. The current stable version is the default, with clear indicators when a user is viewing an older or pre-release version.
+
+## Deprecation notices
+
+When features are deprecated, update docs immediately with a deprecation notice, the version in which deprecation occurred, and a migration path to the replacement.
+
+## Changelog as a first-class document
+
+Treat the changelog as a primary artifact, not an afterthought. Link it prominently from the docs home page and update it as part of the release process. Link migration guides from the changelog entries that introduce breaking changes; highlight breaking changes prominently.
+
+## Write version-agnostic content where possible
+
+Conceptual and explanation content that does not change between versions should avoid version-specific references. This reduces maintenance burden and prevents confusion.
+
+## Docs-as-code for version control
+
+Store docs in the same Git repository as the code (or a closely linked one) so docs version alongside code. Pull requests for code changes include doc updates; CI/CD pipelines can enforce that docs are updated before a release merges.
+
+## Canonical URLs
+
+Versioned docs create a risk of duplicate-content search penalties. Use canonical URL tags pointing search engines to the current stable version of each page.

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

@@ -9,15 +9,16 @@ Read `references/setup.md` for tracker-specific collection commands before revie
 ## Procedure
 
 1. Gather the issue set to review plus the source plan/spec/parent issue when available.
-2. Run the passes in order:
+2. For Beads trackers, run PASS 0 pre-flight checks first: `references/pass-0-preflight.md`
+3. Run the content passes in order:
    - Pass 1: `references/pass-1-clarity.md`
    - Pass 2: `references/pass-2-scope.md`
    - Pass 3: `references/pass-3-dependencies.md`
    - Pass 4: `references/pass-4-alignment.md`
    - Pass 5: `references/pass-5-executability.md`
-3. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
-4. If converged, stop.
-5. Produce the final report using `references/final-report.md`.
+4. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
+5. If converged, stop.
+6. Produce the final report using `references/final-report.md`.
 
 ## Review Lens
 

package/content/distilled/issue-review/references/pass-0-preflight.md

@@ -0,0 +1,37 @@
+# PASS 0: Pre-flight (Beads only)
+
+Run before all content passes. Mechanical checks that don't require reading issue bodies.
+
+**Check 1 — metadata.files coverage:**
+```bash
+bd list --format json | python3 -c "
+import json, sys
+issues = json.load(sys.stdin)
+missing = [i['id'] for i in issues
+           if not (i.get('metadata') or {}).get('files')]
+if missing: print('Missing metadata.files:', missing)
+"
+```
+Flag `[PRE-001] MEDIUM` for each ticket missing `metadata.files`.
+Fix: `bd update <id> --set-metadata 'files=["path/to/file.py"]'`
+
+**Check 2 — shared-file architecture smell:**
+```bash
+bd list --format json | python3 -c "
+import json, sys
+from collections import defaultdict
+issues = json.load(sys.stdin)
+owners = defaultdict(list)
+for i in issues:
+    for f in (i.get('metadata') or {}).get('files', []):
+        owners[f].append(i['id'])
+for f, ids in owners.items():
+    if len(ids) >= 3: print(f, '->', ids)
+"
+```
+Flag `[PRE-002] LOW` for any file claimed by 3+ open tickets.
+Recommendation: consider a decomposition ticket to split `<file>` before these
+tickets run (see navari-a3cv pattern). If not decomposing now, add a
+co-modification note to all affected tickets.
+
+**Prefix:** PRE-001, PRE-002, etc.

package/content/distilled/next/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: next
+description: "Rapid session snapshot to ~/.whisper/ — no full close ceremony. Trigger when the user says '/next', 'snap', 'quick save', 'stash session', or 'moving on'."
+tools: Read, Write, Edit, Bash
+---
+
+# Next
+
+Snapshot the current session to `~/.whisper/` and move on. Fast — no project file updates, no inbox triage, no ticket operations. Pure stash.
+
+## Steps
+
+1. Get timestamp: `date +%Y-%m-%d` and `date +%H:%M`.
+
+2. Detect repo and branch:
+   ```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')
+   notes_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/notes.md
+   ```
+
+3. If `~/.whisper/` doesn't exist or the branch slot doesn't exist, run `/w check` first (which will offer to init). If the user declines, skip and warn.
+
+4. Scan the last portion of the conversation and write a 2–5 bullet snapshot:
+   - What was worked on (files, topics)
+   - Key decisions or changes made
+   - **Next:** the most logical continuation point
+
+5. Append the snapshot to `notes.md`:
+   ```
+   ### YYYY-MM-DD HH:MM — snap
+   - what was worked on
+   - decisions made
+   - **Next:** continuation point
+   ```
+
+6. No commit, no push, no ticket operations. Just write the file.
+
+## Output
+
+```
+✓ Snapped to ~/.whisper/repos/<repo>/branches/<slug>/notes.md
+
+Use `/renew` later to pick this back up.
+```
+
+## Rules
+
+- Do NOT ask questions — summarize automatically from conversation context.
+- Keep it brief — 2–5 bullets, not paragraphs.
+- Do NOT commit or push anything.
+- Do NOT update project files, inbox, or tickets.
+- Do NOT run `/clear`.