diff --git a/plugins/save-doc/commands/release-notes.md b/plugins/save-doc/commands/release-notes.md new file mode 100644 index 0000000..07825cd --- /dev/null +++ b/plugins/save-doc/commands/release-notes.md @@ -0,0 +1,75 @@ +--- +description: "Save release notes for a deployment to the knowledge base" +allowed-tools: Read,Write,Edit,Glob,Grep,Bash +--- + +Save release notes documenting a deployment. Gathers context from git history and produces a structured KB document. + +## Defaults + +- **type:** `reference` +- **tags:** always include `release-notes` and `deployment` +- **filename:** `release-YYYY.M.DD.md` (or `database-release-YYYY.M.DD.md` for DB-only releases) +- **save path:** `/mnt/NV2/Development/claude-home/{domain}/` + +## Gathering Context + +Before writing, collect what you can automatically: + +1. **Git log** — recent commits on `main` since last tag or last release notes +2. **Tags** — latest CalVer tag for the version number +3. **PRs** — merged PR numbers and titles if available +4. **Ask the user** for anything you can't determine: target server, deploy method, image tag, domain + +## Document Structure + +```markdown +--- +title: "{Project} Release — YYYY.M.DD" +description: "One-line summary of what this release covers." +type: reference +domain: {domain} +tags: [release-notes, deployment, ...] +--- + +# {Project} Release — YYYY.M.DD + +**Date:** YYYY-MM-DD +**Tag:** `{calver or semver tag}` +**Image:** `{docker image}` (if applicable) +**Server:** {target host} (`{deploy path}`) +**Deploy method:** {how it was deployed} + +## Release Summary + +One paragraph overview of the release. + +## Changes + +### New Features +- ... + +### Bug Fixes +- ... + +### Dependencies +- ... + +## Infrastructure Changes +(Only if applicable — CI, Docker, config changes) + +## Hotfix During Release +(Only if a hotfix was needed — include root cause and lesson) + +## Deployment Notes +- Migration commands, config changes, rollback instructions +- Rollback: {how to roll back} +``` + +## Rules + +- Omit empty sections — only include sections that have content +- Use PR numbers as references (e.g., "PR #88") when available +- Include rollback instructions when the deployment method supports it +- For database-only releases, prefix filename with `database-` +- If the user provides partial info, fill in what you can and ask about the rest diff --git a/plugins/save-doc/commands/session.md b/plugins/save-doc/commands/session.md new file mode 100644 index 0000000..b8c487f --- /dev/null +++ b/plugins/save-doc/commands/session.md @@ -0,0 +1,76 @@ +--- +description: "Save a session summary capturing work done, decisions made, and follow-ups" +allowed-tools: Read,Write,Edit,Glob,Grep,Bash +--- + +Save a session summary documenting what was accomplished in a working session. Captures decisions, changes, and follow-up items for future context. + +## Defaults + +- **type:** `context` +- **filename:** `YYYY-MM-DD.md` (use the current date) +- **tags:** always include the repo name if work was repo-specific +- **save path:** `/mnt/NV2/Development/claude-home/{domain}/` + +## Gathering Context + +Before writing, collect what you can automatically: + +1. **Git log** — commits made during this session (today's commits, or commits on the current branch) +2. **Branch name** — the working branch +3. **Changed files** — `git diff --stat` for a summary +4. **Issues/PRs** — any created or referenced during the session +5. **Ask the user** for domain if not obvious, and for any decisions or context not captured in commits + +## Document Structure + +```markdown +--- +title: "{Ticket/Topic}: {Brief description of work}" +description: "One-line summary of the session — what was done and in which repo." +type: context +domain: {domain} +tags: [{repo-name}, ...] +--- + +# {Ticket/Topic}: {Brief description} + +**Date:** YYYY-MM-DD +**Branch:** `{branch-name}` +**Repo:** {repo-name} + +## What Was Done + +Narrative summary of the work, followed by a numbered list of specific changes: + +1. **{Change title}** — description of what and why +2. ... + +## Decisions + +Key decisions made during the session and their rationale. Use this format: + +### {Decision title} +{What was decided and why. Include alternatives considered if relevant.} + +## Follow-Up + +| # | Title | Priority | +|---|-------|----------| +| [#{n}](url) | {description} | {High/Medium/Low} | + +Or as a bullet list if issues weren't created: +- {thing that still needs to be done} + +## Files Changed + +- `path/to/file.py` — brief note on what changed +``` + +## Rules + +- Omit empty sections — skip Decisions or Follow-Up if there's nothing to capture +- The title should reference a ticket number or topic, not just a date +- Focus on decisions and "why" — the git log already records "what" +- If multiple repos were touched, note which changes belong to which repo +- Only include file-level change notes when they add context beyond what git shows diff --git a/plugins/save-doc/commands/troubleshooting.md b/plugins/save-doc/commands/troubleshooting.md new file mode 100644 index 0000000..b321266 --- /dev/null +++ b/plugins/save-doc/commands/troubleshooting.md @@ -0,0 +1,78 @@ +--- +description: "Save a troubleshooting entry for a bug fix or incident resolution" +allowed-tools: Read,Write,Edit,Glob,Grep,Bash +--- + +Save a troubleshooting doc capturing a bug fix, incident, or resolved issue. Checks for an existing troubleshooting file in the domain to append to. + +## Defaults + +- **type:** `troubleshooting` +- **tags:** always include `troubleshooting` +- **save path:** `/mnt/NV2/Development/claude-home/{domain}/` + +## Before Writing + +1. **Check for existing file** — look for `{domain}/troubleshooting.md` in the KB directory. If one exists, **append** a new section rather than creating a separate file. +2. **If creating a new standalone file** — use a descriptive hyphenated name (e.g., `scout-token-wallet-fix.md`) +3. **Ask the user** for domain if not obvious from context + +## Document Structure — Standalone File + +```markdown +--- +title: "Fix: {Short description of the problem}" +description: "One-line summary of what broke and why." +type: troubleshooting +domain: {domain} +tags: [troubleshooting, ...] +--- + +# Fix: {Short description} + +**Date:** YYYY-MM-DD +**PR:** #{number} (if applicable) +**Severity:** {Low | Medium | High | Critical} — {brief impact} + +## Problem + +What was happening? What was the user-visible symptom? + +## Root Cause + +Why was it happening? Be specific about the code path or misconfiguration. + +## Fix + +What was changed? Include the approach, not a full diff. + +## Lessons + +- What should be done differently in the future? +- Any new tests, guards, or patterns established? +``` + +## Document Structure — Appending to Existing File + +When appending to an existing `troubleshooting.md`, add a new `##` section with this format: + +```markdown +## {Short description} ({YYYY-MM-DD}) + +**Severity:** {level} — {impact} + +**Problem:** {symptom} + +**Root Cause:** {why} + +**Fix:** {what changed} + +**Lesson:** {takeaway} +``` + +## Rules + +- Always check for an existing troubleshooting file first +- Include severity to help prioritize similar issues in the future +- Focus on the "why" in Root Cause — not just "what was wrong" but why it happened +- Lessons should be actionable — patterns to follow or avoid, not just "be more careful"