From a836ba3f02eddef8023efecf3cdf152099ca23e3 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Fri, 10 Apr 2026 11:26:42 -0400 Subject: [PATCH 1/3] feat(pr-ready): add doc-check step between changelog and create-pr MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every PR ships without anyone asking "does this need README / ROADMAP / CLAUDE.md updates?" because the author forgets and there's no step in the pipeline that forces the question. Add a `doc-check` step to the pr-ready workflow that runs after `changelog` and before `create-pr`. The step classifies the diff (feature / bugfix / breaking / internal / docs-only) and walks a rule table for each candidate doc at the repo root — README.md, ROADMAP.md, CLAUDE.md / AGENTS.md, docs/, plugin.json and other manifests, workflows/*.yml — deciding per-file whether this PR requires an update. CHANGELOG.md is explicitly skipped because it is owned by the release pipeline, not individual PRs. Mechanical edits (moving a ROADMAP bullet from Planned to Implemented, adding a README command row, renaming a manifest entry) are applied directly via Edit/Write and committed with `docs: update for ` so they land in the PR alongside the code. Ambiguous updates are emitted as `[!]` TODO entries in the checklist output so the user sees exactly what still needs manual attention before `create-pr` runs. Also updates skills/pr-ready/SKILL.md to reflect the new 9-step pipeline. Verified the YAML parses and step order is validate → necessity → lint → test → security → changelog → doc-check → create-pr → monitor --- skills/pr-ready/SKILL.md | 7 ++-- workflows/pr-ready.yml | 76 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 3 deletions(-) diff --git a/skills/pr-ready/SKILL.md b/skills/pr-ready/SKILL.md index 45282c5..2d44277 100644 --- a/skills/pr-ready/SKILL.md +++ b/skills/pr-ready/SKILL.md @@ -5,7 +5,7 @@ description: Full PR pipeline — use when asked to submit a PR, create a pull r # PR Ready -Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → changelog → create PR → monitor (loop). +Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → changelog → doc-check → create PR → monitor (loop). ## Invoke @@ -23,8 +23,9 @@ Then follow each step the engine returns. Call `devkit_advance` after completing 4. **test** — runs test suite, fixes failures, loops until passing 5. **security** — scans for hardcoded secrets, injection, XSS, traversal, insecure deps 6. **changelog** — generates entry from git diff -7. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan -8. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved +7. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, docs/, plugin.json, or workflows/ need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. +8. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan +9. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved ## Rules diff --git a/workflows/pr-ready.yml b/workflows/pr-ready.yml index e994a60..fcf76a1 100644 --- a/workflows/pr-ready.yml +++ b/workflows/pr-ready.yml @@ -63,6 +63,82 @@ steps: Generate a changelog entry from git diff main...HEAD. Summarize what changed and why. + - id: doc-check + model: smart + prompt: | + Classify the diff (git diff main...HEAD) and decide which project + docs need updating so the user does not have to ask every PR. + + STEP 1 — Classify the change as exactly one of: + - feature (new user-visible capability) + - bugfix (fixes existing behaviour) + - breaking (removes/renames public surface, bumps required version, changes CLI/flag semantics) + - internal (refactor, test, CI, build, infra — no user impact) + - docs-only (README/CHANGELOG/ROADMAP/comments only) + + STEP 2 — Enumerate candidate docs that exist at repo root and + decide per-file whether this PR requires an update. Use these + rules (each rule lists the classifications that force an update; + internal/docs-only PRs default to "not affected" unless stated): + + - README.md + * feature: update if user-facing commands, install steps, or + the feature table changed. + * breaking: always update — migration note + changed surface. + * bugfix/internal: not affected unless README directly + describes the broken behaviour. + + - ROADMAP.md + * feature: move the corresponding entry from "Planned" to + "Implemented", or add a new Implemented bullet. + * breaking: update if a roadmap item is now removed. + * bugfix/internal: not affected. + + - CHANGELOG.md + * Managed by the release pipeline, not individual PRs. Never + write to it here unless the PR is an explicit release bump + (plugin.json version change). + + - CLAUDE.md (or AGENTS.md) + * feature/breaking: update if project conventions, tool + selection rules, or workflow patterns changed. + * bugfix/internal: not affected. + + - docs/ or *.md under docs/ + * feature: update if an existing doc describes the subsystem + you touched. + * breaking: always update. + + - plugin.json / manifest.json / .claude-plugin/ + * breaking: update if commands, skills, agents, or MCP + servers were added/removed/renamed. + * feature: update if a new command/skill/agent is exposed. + * bugfix/internal: not affected unless the bug was a missing + manifest entry. + + - workflows/*.yml + * feature: add/update if a workflow step was added or its + contract changed. + * internal: only if a workflow file itself was refactored. + + STEP 3 — For each doc decided "needs update", either apply the + edit directly (Edit/Write tool) if the change is mechanical and + unambiguous (moving a roadmap bullet, adding a README command + row, renaming a manifest entry), OR emit a one-line TODO with + the exact edit the user needs to make. + + STEP 4 — Output a markdown checklist of ALL candidate docs: + - [x] README.md — updated: + - [ ] ROADMAP.md — not affected (bugfix) + - [ ] CHANGELOG.md — managed by release pipeline + - [!] CLAUDE.md — needs manual update: + Use [x] for applied updates, [ ] for not-affected, [!] for + needs-manual-update. + + Commit any applied edits with message + docs: update for + so the doc changes land in the PR alongside the code. + - id: create-pr model: smart prompt: | From c5a718d1fcb0d307f35adb7bce7d9414fa02e59a Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Fri, 10 Apr 2026 11:31:25 -0400 Subject: [PATCH 2/3] docs: sync hooks/pr-gate.sh pipeline list with actual steps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The user-facing prompt in pr-gate.sh enumerated the pr-ready pipeline as "lint, test, security, DRY review, changelog, monitor" — which was already stale (no "DRY review" step exists) and is now also missing the new doc-check step added in this PR. Updated to match the actual workflow order after doc-check: lint, test, security, changelog, doc-check, monitor Found by running this PR's own doc-check rules on itself — this is exactly the kind of stale mechanical reference doc-check is meant to catch automatically on future PRs. --- hooks/pr-gate.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hooks/pr-gate.sh b/hooks/pr-gate.sh index ee3987d..ca1ec27 100755 --- a/hooks/pr-gate.sh +++ b/hooks/pr-gate.sh @@ -36,7 +36,7 @@ jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", - permissionDecisionReason: "PR creation detected — want to run the pr-ready pipeline first? (lint, test, security, DRY review, changelog, monitor). Say yes to run it, or approve to skip and create the PR directly." + permissionDecisionReason: "PR creation detected — want to run the pr-ready pipeline first? (lint, test, security, changelog, doc-check, monitor). Say yes to run it, or approve to skip and create the PR directly." } }' exit 0 From 0b7a42758647dab776bd067698c0211de14c2569 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Fri, 10 Apr 2026 11:35:52 -0400 Subject: [PATCH 3/3] review fix: run doc-check before changelog, add skills/*/SKILL.md rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code review on PR #56 flagged that `doc-check` was ordered after `changelog`, so any `docs: update ...` commit the step creates would not be reflected in the changelog summary that `create-pr` uses for the PR body. Swap the order to doc-check → changelog → create-pr so the changelog always sees doc-check's commits. Also expand the doc-check rule table with a `skills/*/SKILL.md` entry the review suggested was missing. SKILL.md files are a first-class user-facing surface in this repo and were not covered by the previous rules — which meant a workflow step change could slip through without syncing the matching skill's step list. New rule: edits to a `workflows/*.yml` file require the matching `skills//SKILL.md` step list to be synced, and SKILL.md mismatches are flagged as needs-update. (This PR would have caught its own manual SKILL.md update automatically under the new rule.) Updated skills/pr-ready/SKILL.md to reflect: - new order (doc-check → changelog) - skills/*/SKILL.md in the candidate list - "Runs before changelog so ..." explanation --- skills/pr-ready/SKILL.md | 6 +++--- workflows/pr-ready.yml | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/skills/pr-ready/SKILL.md b/skills/pr-ready/SKILL.md index 2d44277..d7cfc8f 100644 --- a/skills/pr-ready/SKILL.md +++ b/skills/pr-ready/SKILL.md @@ -5,7 +5,7 @@ description: Full PR pipeline — use when asked to submit a PR, create a pull r # PR Ready -Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → changelog → doc-check → create PR → monitor (loop). +Deterministic PR pipeline: validate → necessity → lint (loop) → test (loop) → security → doc-check → changelog → create PR → monitor (loop). ## Invoke @@ -22,8 +22,8 @@ Then follow each step the engine returns. Call `devkit_advance` after completing 3. **lint** — runs linter, fixes violations, loops until clean 4. **test** — runs test suite, fixes failures, loops until passing 5. **security** — scans for hardcoded secrets, injection, XSS, traversal, insecure deps -6. **changelog** — generates entry from git diff -7. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, docs/, plugin.json, or workflows/ need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. +6. **doc-check** — classifies the diff (feature/bugfix/breaking/internal/docs-only) and decides per-file whether README, ROADMAP, CLAUDE.md, docs/, `skills/*/SKILL.md`, plugin.json, or `workflows/*.yml` need updates. Applies mechanical edits directly (moving roadmap bullets, adding command rows, syncing SKILL.md step lists); flags ambiguous updates as `[!]` in the output checklist. Commits applied edits with `docs: update ...` so they land in the PR alongside the code. CHANGELOG.md is intentionally skipped — it is managed by the release pipeline. Runs **before** `changelog` so any doc commit it creates is captured in the PR description. +7. **changelog** — generates entry from git diff (now includes any doc-check commits) 8. **create-pr** — pushes branch, creates PR via gh pr create with title/summary/changelog/test plan 9. **monitor** — waits for CI, classifies reviewer comments (code_fix/style_nit/question/false_positive/out_of_scope), applies fixes, replies, pushes, loops until all resolved diff --git a/workflows/pr-ready.yml b/workflows/pr-ready.yml index fcf76a1..ff8b9f1 100644 --- a/workflows/pr-ready.yml +++ b/workflows/pr-ready.yml @@ -57,18 +57,16 @@ steps: Report findings with severity and file:line references. - - id: changelog - model: fast - prompt: | - Generate a changelog entry from git diff main...HEAD. - Summarize what changed and why. - - id: doc-check model: smart prompt: | Classify the diff (git diff main...HEAD) and decide which project docs need updating so the user does not have to ask every PR. + This step runs BEFORE `changelog` so any `docs: update ...` commit + it creates is included in the changelog summary that `create-pr` + uses for the PR body. + STEP 1 — Classify the change as exactly one of: - feature (new user-visible capability) - bugfix (fixes existing behaviour) @@ -109,6 +107,15 @@ steps: you touched. * breaking: always update. + - skills/*/SKILL.md + * feature: update the affected skill's SKILL.md if a new + step, capability, or contract is added. + * breaking: update if a skill's invocation shape, step list, + or frontmatter description changed. + * If a `workflows/*.yml` file was edited, the matching + `skills//SKILL.md` step list MUST be kept + in sync — treat mismatches as a needs-update. + - plugin.json / manifest.json / .claude-plugin/ * breaking: update if commands, skills, agents, or MCP servers were added/removed/renamed. @@ -118,14 +125,16 @@ steps: - workflows/*.yml * feature: add/update if a workflow step was added or its - contract changed. + contract changed. When you edit a workflow, re-check the + matching SKILL.md rule above. * internal: only if a workflow file itself was refactored. STEP 3 — For each doc decided "needs update", either apply the edit directly (Edit/Write tool) if the change is mechanical and unambiguous (moving a roadmap bullet, adding a README command - row, renaming a manifest entry), OR emit a one-line TODO with - the exact edit the user needs to make. + row, renaming a manifest entry, syncing a SKILL.md step list), + OR emit a one-line TODO with the exact edit the user needs to + make. STEP 4 — Output a markdown checklist of ALL candidate docs: - [x] README.md — updated: @@ -137,7 +146,16 @@ steps: Commit any applied edits with message docs: update for - so the doc changes land in the PR alongside the code. + so the doc changes land in the PR alongside the code and the + subsequent `changelog` step picks them up. + + - id: changelog + model: fast + prompt: | + Generate a changelog entry from git diff main...HEAD. + Summarize what changed and why. Any `docs: update ...` commit + created by the preceding `doc-check` step is in HEAD now and + must be reflected in this summary. - id: create-pr model: smart