diff --git a/README.md b/README.md index e870dab..fa4333b 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ Invoked with `/ctx:`. | `ctx-worktree` | Isolated git worktree with env files and deps, ready immediately. | | `ctx-kill-wt` | Teardown: kill port, remove worktree, delete branch. | | `ctx-open` | Open current directory in WebStorm. | -| `ctx-docs` | Aggregate completed work into epic documentation from specs, plans, parks, and git history. | +| `ctx-docs` | Create evidence-grounded architecture checkpoint docs with source-of-truth boundaries, verification, and Mermaid diagrams. | **Calibration** diff --git a/plugins/ctx-codex/skills/ctx-docs/SKILL.md b/plugins/ctx-codex/skills/ctx-docs/SKILL.md index 994ada9..5c648a0 100644 --- a/plugins/ctx-codex/skills/ctx-docs/SKILL.md +++ b/plugins/ctx-codex/skills/ctx-docs/SKILL.md @@ -1,124 +1,172 @@ --- name: ctx-docs description: > - Aggregate completed work into human-readable epic documentation. - Use when an epic or batch of issues is complete and you want a documentation - package. Triggers: "document this epic", "generate docs", "ctx-docs", - or after a batch of issues is shipped. + Create architecture checkpoint documentation for completed work. Use when the + user asks to document what was just built, document task or phase completion, + explain current migration state, capture source-of-truth boundaries, generate + docs with Mermaid diagrams, or run "ctx-docs". Produces evidence-grounded docs + from existing code, tests, migrations, and docs; not Linear-first. user-invocable: true allowed-tools: Bash, Read, Glob, Grep, Write --- -# ctx-docs — Epic Documentation Aggregation +# ctx-docs — Architecture Checkpoint Documentation -Synthesize completed work into structured, human-readable docs. Pulls from Linear, specs, plans, git history, and distilled memories. +Create a human-readable checkpoint doc for completed technical work. The goal is to preserve the current system boundary: what changed, why it matters, how it works, how to verify it, and what remains. + +Do not default to Linear or issue aggregation. Treat code, migrations, tests, and existing docs as the primary evidence. --- -## 1. Parse arguments +## 1. Define The Checkpoint + +Start by naming the completed slice in plain language: + +- `auth-identity-postgres-task-3` +- `billing-postgres-cutover` +- `playbook-runtime-v1` +- `company-list-postgres-phase-1` -Two entry points: +If the user did not give a title, derive one from the current branch, changed files, or the user's wording. -- **Epic mode:** `ctx-docs ` — queries Linear for the epic/project's issues -- **Issue mode:** `ctx-docs CTX-33 CTX-28 CTX-16` — user provides issue IDs directly +Use one doc unless the user asks for a full documentation package. Put the doc near existing related docs: -`` is always required — becomes the directory name and index title. +- feature docs under the local app docs directory when one exists, e.g. `src/coreties-app/docs/` +- project-wide docs under `docs/` +- diagrams under a colocated `diagrams//` directory when standalone Mermaid files are useful -If no issue IDs provided, use the Linear MCP (`mcp__plugin_linear_linear__list_issues`) to find issues belonging to the named epic/project. If Linear is unavailable or returns nothing, ask the user for issue IDs. +Do not commit unless the user explicitly asks. --- -## 2. Resolve issues +## 2. Gather Evidence -For each issue ID: -1. Fetch metadata from Linear via `mcp__plugin_linear_linear__get_issue` (title, description, status, labels) -2. If Linear unavailable, proceed with issue ID only — artifact discovery still works +Read narrowly, then expand only as needed. Prefer `rg` and targeted file reads. ---- +Minimum evidence set: -## 3. Gather artifacts +- existing docs related to the same feature, migration, or architecture area +- changed or referenced service files +- changed or referenced API entrypoints +- relevant migrations or schema definitions +- relevant tests +- current git status -For each issue, scan these locations: +For migration/source-of-truth work, explicitly find: -| Artifact | Location | Match strategy | -|----------|----------|---------------| -| Spec | `docs/specs/*.md` | Grep for issue ID in filename or content | -| Plan | `~/.codex/ctx-codex/plans/*.md` | Grep for issue ID in content | -| Park smart context | `docs/ctx/park.md` or git history | Branch name or issue ID reference | -| Git history | `git log --all --oneline --grep="{issue-id}"` | Commit messages | -| Linear metadata | From step 2 | Already fetched | -| Distilled memories | `~/.codex/ctx-codex/projects//memory/*.md` | Grep for issue ID in content or description | +- current source of truth +- previous source of truth +- write paths +- read paths +- fallbacks or dual-write behavior +- compatibility side effects +- verification commands +- remaining migration boundary -Not every issue will have every artifact. Work with what exists — skip missing artifacts gracefully. +If an older doc conflicts with current code, state the current code-backed boundary and mention the doc gap. --- -## 4. Generate docs - -Create `docs/ctx//` with: +## 3. Write The Doc -### `index.md` +Use this structure by default. Omit sections only when they genuinely do not apply. ````markdown -# - -**Generated:** {timestamp} -**Issues:** {N} completed -**Branches:** {list} +# -## Summary +This document summarizes and relates it to the existing docs. -{2-3 paragraph narrative synthesized from specs and plans} +## Status -## Issues +{What is now true. Include exact boundary language.} -| ID | Title | Complexity | Status | Branch | -|----|-------|-----------|--------|--------| -| ... | ... | ... | ... | ... | +## Why This Exists -## Key Decisions +{Problem before the change and why the new boundary is useful.} -{Aggregated from park smart context and spec "Why this approach" sections — only non-obvious decisions} +## Data Model -## Learnings +{Tables, contracts, schemas, durable ids, source keys, or state objects.} -{Aggregated from distilled memories related to these issues} -```` +## Runtime Write Path -### Per-issue docs (`.md`) +{Who writes what, in what order, and transaction/side-effect boundaries.} -````markdown -# — {title} +## Entry Points Updated -**Status:** {from Linear or git} -**Branch:** {from git} -**Spec:** {relative path to spec file, if found} -**Plan:** {relative path to plan file, if found} +| Path | Role | +| --- | --- | +| ... | ... | -## Design +## Reader Behavior -{From spec — problem, chosen approach, tradeoffs} +{What reads the new source first, what falls back, and what remains legacy.} -## Implementation +## What Changed About -{From plan — what was built, key files touched} +{Be explicit about what did not disappear. Name fallbacks and side effects.} -## Outcome +## Verification -{From git log — commits. From park — what actually happened} +{Focused tests, manual SQL/API checks, and behavioral checks.} -## Learnings +## Remaining Migration Boundary -{From park smart context + distilled memories} +{What is intentionally not done yet.} ```` -If a section has no data (e.g., no park file found), omit that section rather than writing "N/A". +### Boundary Language Rules + +- Do not write "migrated" without naming the migrated slice. +- Do not imply the whole product is on the new architecture unless the evidence proves it. +- Separate authentication source, app identity source, analytics source, billing source, and workflow state source when those are different. +- Name legacy fallbacks directly. +- Name compatibility side effects directly. +- Prefer "Postgres-owned for these updated paths" over broad claims like "Postgres-only." --- -## 5. Commit +## 4. Add Mermaid Diagrams + +For system-boundary docs, include both embedded Mermaid blocks in the markdown and standalone `.mmd` files when useful. + +Default diagrams: + +1. **Runtime flow**: request/event -> service -> transaction -> tables/side effects +2. **Entrypoint map**: routes/jobs/events -> shared service -> stores +3. **Reader boundary**: new source -> fallback -> behavior +4. **Before/after ownership**: old source vs new source when the migration is confusing -```bash -git add docs/ctx// -git commit -m "docs: epic documentation" +Use diagrams to clarify ownership and flow. Do not add decorative diagrams. + +Standalone file convention: + +```text +/diagrams//runtime-flow.mmd +/diagrams//entrypoints.mmd +/diagrams//reader-boundary.mmd +``` + +Keep Mermaid syntax simple: + +```mermaid +flowchart TD + A[External source] --> B[Shared service] + B --> C[New durable store] + B --> D[Legacy side effect] ``` + +--- + +## 5. Verify The Documentation + +Before reporting back: + +- confirm the doc file exists +- confirm any standalone `.mmd` files exist +- re-read the generated doc for overclaims +- check that links point to real local files where practical +- run a focused search for the main terms to ensure the doc names the actual code paths +- report verification commands run + +Do not claim tests pass unless you ran the tests. For docs-only changes, file existence, content checks, link sanity, and git status are usually the right verification. diff --git a/plugins/ctx/skills/ctx-docs/SKILL.md b/plugins/ctx/skills/ctx-docs/SKILL.md index cc6735f..64d2712 100644 --- a/plugins/ctx/skills/ctx-docs/SKILL.md +++ b/plugins/ctx/skills/ctx-docs/SKILL.md @@ -1,124 +1,172 @@ --- name: ctx-docs description: > - Aggregate completed work into human-readable epic documentation. - Use when an epic or batch of issues is complete and you want a documentation - package. Triggers: "document this epic", "generate docs", "ctx-docs", - or after a batch of issues is shipped. + Create architecture checkpoint documentation for completed work. Use when the + user asks to document what was just built, document task or phase completion, + explain current migration state, capture source-of-truth boundaries, generate + docs with Mermaid diagrams, or run "/ctx-docs". Produces evidence-grounded docs + from existing code, tests, migrations, and docs; not Linear-first. user-invocable: true allowed-tools: Bash, Read, Glob, Grep, Write --- -# /ctx-docs — Epic Documentation Aggregation +# /ctx-docs — Architecture Checkpoint Documentation -Synthesize completed work into structured, human-readable docs. Pulls from Linear, specs, plans, git history, and distilled memories. +Create a human-readable checkpoint doc for completed technical work. The goal is to preserve the current system boundary: what changed, why it matters, how it works, how to verify it, and what remains. + +Do not default to Linear or issue aggregation. Treat code, migrations, tests, and existing docs as the primary evidence. --- -## 1. Parse arguments +## 1. Define The Checkpoint + +Start by naming the completed slice in plain language: + +- `auth-identity-postgres-task-3` +- `billing-postgres-cutover` +- `playbook-runtime-v1` +- `company-list-postgres-phase-1` -Two entry points: +If the user did not give a title, derive one from the current branch, changed files, or the user's wording. -- **Epic mode:** `/ctx-docs ` — queries Linear for the epic/project's issues -- **Issue mode:** `/ctx-docs CTX-33 CTX-28 CTX-16` — user provides issue IDs directly +Use one doc unless the user asks for a full documentation package. Put the doc near existing related docs: -`` is always required — becomes the directory name and index title. +- feature docs under the local app docs directory when one exists, e.g. `src/coreties-app/docs/` +- project-wide docs under `docs/` +- diagrams under a colocated `diagrams//` directory when standalone Mermaid files are useful -If no issue IDs provided, use the Linear MCP (`mcp__plugin_linear_linear__list_issues`) to find issues belonging to the named epic/project. If Linear is unavailable or returns nothing, ask the user for issue IDs. +Do not commit unless the user explicitly asks. --- -## 2. Resolve issues +## 2. Gather Evidence -For each issue ID: -1. Fetch metadata from Linear via `mcp__plugin_linear_linear__get_issue` (title, description, status, labels) -2. If Linear unavailable, proceed with issue ID only — artifact discovery still works +Read narrowly, then expand only as needed. Prefer `rg` and targeted file reads. ---- +Minimum evidence set: -## 3. Gather artifacts +- existing docs related to the same feature, migration, or architecture area +- changed or referenced service files +- changed or referenced API entrypoints +- relevant migrations or schema definitions +- relevant tests +- current git status -For each issue, scan these locations: +For migration/source-of-truth work, explicitly find: -| Artifact | Location | Match strategy | -|----------|----------|---------------| -| Spec | `docs/specs/*.md` | Grep for issue ID in filename or content | -| Plan | `~/.claude/plugins/marketplaces/ctx-plugin/plans/*.md` | Grep for issue ID in content | -| Park smart context | `docs/ctx/park.md` or git history | Branch name or issue ID reference | -| Git history | `git log --all --oneline --grep="{issue-id}"` | Commit messages | -| Linear metadata | From step 2 | Already fetched | -| Distilled memories | `~/.claude/projects//memory/*.md` | Grep for issue ID in content or description | +- current source of truth +- previous source of truth +- write paths +- read paths +- fallbacks or dual-write behavior +- compatibility side effects +- verification commands +- remaining migration boundary -Not every issue will have every artifact. Work with what exists — skip missing artifacts gracefully. +If an older doc conflicts with current code, state the current code-backed boundary and mention the doc gap. --- -## 4. Generate docs - -Create `docs/ctx//` with: +## 3. Write The Doc -### `index.md` +Use this structure by default. Omit sections only when they genuinely do not apply. ````markdown -# - -**Generated:** {timestamp} -**Issues:** {N} completed -**Branches:** {list} +# -## Summary +This document summarizes and relates it to the existing docs. -{2-3 paragraph narrative synthesized from specs and plans} +## Status -## Issues +{What is now true. Include exact boundary language.} -| ID | Title | Complexity | Status | Branch | -|----|-------|-----------|--------|--------| -| ... | ... | ... | ... | ... | +## Why This Exists -## Key Decisions +{Problem before the change and why the new boundary is useful.} -{Aggregated from park smart context and spec "Why this approach" sections — only non-obvious decisions} +## Data Model -## Learnings +{Tables, contracts, schemas, durable ids, source keys, or state objects.} -{Aggregated from distilled memories related to these issues} -```` +## Runtime Write Path -### Per-issue docs (`.md`) +{Who writes what, in what order, and transaction/side-effect boundaries.} -````markdown -# — {title} +## Entry Points Updated -**Status:** {from Linear or git} -**Branch:** {from git} -**Spec:** {relative path to spec file, if found} -**Plan:** {relative path to plan file, if found} +| Path | Role | +| --- | --- | +| ... | ... | -## Design +## Reader Behavior -{From spec — problem, chosen approach, tradeoffs} +{What reads the new source first, what falls back, and what remains legacy.} -## Implementation +## What Changed About -{From plan — what was built, key files touched} +{Be explicit about what did not disappear. Name fallbacks and side effects.} -## Outcome +## Verification -{From git log — commits. From park — what actually happened} +{Focused tests, manual SQL/API checks, and behavioral checks.} -## Learnings +## Remaining Migration Boundary -{From park smart context + distilled memories} +{What is intentionally not done yet.} ```` -If a section has no data (e.g., no park file found), omit that section rather than writing "N/A". +### Boundary Language Rules + +- Do not write "migrated" without naming the migrated slice. +- Do not imply the whole product is on the new architecture unless the evidence proves it. +- Separate authentication source, app identity source, analytics source, billing source, and workflow state source when those are different. +- Name legacy fallbacks directly. +- Name compatibility side effects directly. +- Prefer "Postgres-owned for these updated paths" over broad claims like "Postgres-only." --- -## 5. Commit +## 4. Add Mermaid Diagrams + +For system-boundary docs, include both embedded Mermaid blocks in the markdown and standalone `.mmd` files when useful. + +Default diagrams: + +1. **Runtime flow**: request/event -> service -> transaction -> tables/side effects +2. **Entrypoint map**: routes/jobs/events -> shared service -> stores +3. **Reader boundary**: new source -> fallback -> behavior +4. **Before/after ownership**: old source vs new source when the migration is confusing -```bash -git add docs/ctx// -git commit -m "docs: epic documentation" +Use diagrams to clarify ownership and flow. Do not add decorative diagrams. + +Standalone file convention: + +```text +/diagrams//runtime-flow.mmd +/diagrams//entrypoints.mmd +/diagrams//reader-boundary.mmd +``` + +Keep Mermaid syntax simple: + +```mermaid +flowchart TD + A[External source] --> B[Shared service] + B --> C[New durable store] + B --> D[Legacy side effect] ``` + +--- + +## 5. Verify The Documentation + +Before reporting back: + +- confirm the doc file exists +- confirm any standalone `.mmd` files exist +- re-read the generated doc for overclaims +- check that links point to real local files where practical +- run a focused search for the main terms to ensure the doc names the actual code paths +- report verification commands run + +Do not claim tests pass unless you ran the tests. For docs-only changes, file existence, content checks, link sanity, and git status are usually the right verification.