incitaciones 0.2.0 → 0.3.1

package/pi-package/skills/create-issues/SKILL.md

@@ -60,6 +60,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/pi-package/skills/implement-documentation/SKILL.md

@@ -8,67 +8,28 @@ metadata:
 
 Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
 
-## CRITICAL RULES
+## Core 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).
+- 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).
 
-## Implementation Workflow
+## Procedure
 
-### Step 1: Quadrant Check
+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`.
 
-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.
+## Rules
 
-### Step 2: EPPO Initialization
+- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.
 
-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."
+## Related Skills
 
-### 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)
-```
+- `research-documentation` — audit before writing.
+- `review-documentation` — review after writing.

package/pi-package/skills/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/pi-package/skills/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/pi-package/skills/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/pi-package/skills/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/pi-package/skills/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/pi-package/skills/issue-review/SKILL.md

@@ -15,15 +15,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/pi-package/skills/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/pi-package/skills/next/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: next
+description: "Rapid session snapshot to ~/.whisper/ — no full close ceremony. Fast stash for later resumption via /renew"
+metadata:
+  installed-from: "incitaciones"
+---
+---
+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`.

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

@@ -0,0 +1,104 @@
+---
+name: park
+description: "Snapshot current work before switching context. Logs to daily journal, releases ticket claims, records to ~/.whisper/"
+metadata:
+  installed-from: "incitaciones"
+---
+---
+name: park
+description: "Snapshot current work before switching context. Logs what was done and what's next without ending the day. Trigger when the user says '/park', 'park this', 'switching to', 'pause this', or 'context switch'."
+tools: Read, Write, Edit, Bash
+---
+
+# Park
+
+Snapshot the current session's work on a project/area before switching context. This is NOT end-of-day — just a context switch.
+
+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. Get today's date and current time (`date +%Y-%m-%d`, `date +%H:%M`).
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
+   ```
+
+2. Read today's log: `$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`
+   If it doesn't exist, create it with the daily log template.
+
+3. Review the conversation history to determine:
+   - What project/area was being worked on
+   - What was accomplished in this session
+   - What the logical next step is
+   - Any new tasks, decisions, or blockers discovered
+
+4. Append a session entry to today's log under `## Log`:
+   ```
+   ### Session:HH:MM (<project/area context>)
+   - what was done
+   - decisions made
+   - **Next:** what to do when resuming
+   ```
+
+5. Update the relevant project/area file if needed:
+   - Mark completed tasks `[x]`
+   - Add new tasks discovered during the session
+   - Add/update `[~]` waiting items with context
+   - Update `## Notes` with any decisions
+
+6. If there are uncommitted changes in the project's git worktree, note them in the log entry.
+
+7. **Release any in-progress ticket claim if leaving mid-work.**
+   Check whether a ticket was claimed for this session:
+   ```bash
+   BRANCH=$(git branch --show-current 2>/dev/null)
+   bd list --status in_progress --label branch:$BRANCH 2>/dev/null
+   ```
+   For each in-progress ticket that is NOT complete:
+   - **If meaningful work was committed:** keep the claim and append a progress note:
+     ```bash
+     bd note <id> "Session parked $(date +%H:%M). Done: <brief>. Safe to resume from: <last commit>."
+     ```
+   - **If nothing was committed:** release the claim so another agent can pick it up:
+     ```bash
+     bd update <id> --assignee "" --status open
+     ```
+
+8. **Record snapshot to `~/.whisper/`.** If `~/.whisper/` exists and a beads-epic is linked, append a note to the epic:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch_slug=$(git rev-parse --abbrev-ref HEAD | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   beads_epic=$(grep '^beads-epic:' "$context_path" 2>/dev/null | sed 's/^beads-epic: *//')
+   if [ -n "$beads_epic" ]; then
+     bd note "$beads_epic" "Parked $(date +%H:%M). Done: <what was accomplished>. Next: <the logical continuation>."
+   fi
+   ```
+
+9. Do NOT commit/push the journal repo yet — that happens at `/close`. Just write the files.
+
+## Output format
+
+```
+---
+**Parked: <project/area name>**
+
+**Session summary**
+- what was accomplished
+
+**Next step** *(for when you /renew)*
+- the logical continuation
+
+**Updated**
+- files modified in status repo (log, project file, etc.)
+
+*Ready to switch context. Use `/renew <slug>` to pick up something else.*
+```
+
+## Rules
+
+- Do NOT ask questions — summarize automatically from conversation context.
+- Keep it brief — this is a quick snapshot, not a full report.
+- Do NOT commit or push the journal repo.
+- Do NOT run `/clear` — the user may continue working in this session.