diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 5ebf20002..3f69ddda2 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -899,21 +899,3 @@ When significant gaps are found, suggest running `/document-generate` to fill th > **STOP.** Before auditing each doc file and applying updates, polishing CHANGELOG voice, checking cross-doc consistency, cleaning up TODOS, the VERSION bump, and committing (Steps 2-9, after the coverage map in Step 1.5), Read `~/.claude/skills/gstack/document-release/sections/release-body.md` and execute it > in full. Do not work from memory — that section is the source of truth for this step. - ---- - -## Important Rules - -- **Read before editing.** Always read the full content of a file before modifying it. -- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries. -- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes. -- **Be explicit about what changed.** Every edit gets a one-line summary. -- **Generic heuristics, not project-specific.** The audit checks work on any repo. -- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. -- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body - and future work. It does NOT auto-generate missing documentation pages or sections. When gaps - are found, suggest `/document-generate` as the follow-up skill. -- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not - auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. -- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person - who hasn't seen the code. diff --git a/document-release/SKILL.md.tmpl b/document-release/SKILL.md.tmpl index 7621cb312..6be52121f 100644 --- a/document-release/SKILL.md.tmpl +++ b/document-release/SKILL.md.tmpl @@ -140,21 +140,3 @@ When significant gaps are found, suggest running `/document-generate` to fill th --- {{SECTION:release-body}} - ---- - -## Important Rules - -- **Read before editing.** Always read the full content of a file before modifying it. -- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries. -- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes. -- **Be explicit about what changed.** Every edit gets a one-line summary. -- **Generic heuristics, not project-specific.** The audit checks work on any repo. -- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. -- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body - and future work. It does NOT auto-generate missing documentation pages or sections. When gaps - are found, suggest `/document-generate` as the follow-up skill. -- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not - auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. -- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person - who hasn't seen the code. diff --git a/document-release/sections/release-body.md b/document-release/sections/release-body.md index 0f05f13b5..8b593e8c5 100644 --- a/document-release/sections/release-body.md +++ b/document-release/sections/release-body.md @@ -475,3 +475,21 @@ Substitute: STATUS = "clean" if no gaps, "issues_found" if gaps exist. SOURCE = **Cleanup:** Run `rm -f "$TMPERR_DOC"` after processing (if Codex was used). --- + +--- + +## Important Rules + +- **Read before editing.** Always read the full content of a file before modifying it. +- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries. +- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes. +- **Be explicit about what changed.** Every edit gets a one-line summary. +- **Generic heuristics, not project-specific.** The audit checks work on any repo. +- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. +- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body + and future work. It does NOT auto-generate missing documentation pages or sections. When gaps + are found, suggest `/document-generate` as the follow-up skill. +- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not + auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. +- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person + who hasn't seen the code. diff --git a/document-release/sections/release-body.md.tmpl b/document-release/sections/release-body.md.tmpl index 475e8b258..2320cede3 100644 --- a/document-release/sections/release-body.md.tmpl +++ b/document-release/sections/release-body.md.tmpl @@ -360,3 +360,21 @@ If all coverage is complete and no diagrams drifted, output: "Coverage: all ship --- {{CODEX_DOC_REVIEW}} + +--- + +## Important Rules + +- **Read before editing.** Always read the full content of a file before modifying it. +- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries. +- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes. +- **Be explicit about what changed.** Every edit gets a one-line summary. +- **Generic heuristics, not project-specific.** The audit checks work on any repo. +- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. +- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body + and future work. It does NOT auto-generate missing documentation pages or sections. When gaps + are found, suggest `/document-generate` as the follow-up skill. +- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not + auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. +- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person + who hasn't seen the code.