diff --git a/modules/agents.nix b/modules/agents.nix index a4fcde4..9204290 100644 --- a/modules/agents.nix +++ b/modules/agents.nix @@ -13,6 +13,7 @@ let - Pick the API whose behavior doesn't exceed what your tests constrain; extra capability is behavior no test pins down — the kind mutation testing surfaces as surviving mutants. - Keep config files free of keys whose value equals the tool's built-in default, unless the key pins a value against an upstream change; record that intent in the commit message, not an inline comment unless the file would be misleading without it. - Look in git history and commit messages for past rationale, and record current rationale there rather than in comments. + - Use the commit skill for commits, the merge-request skill for opening or updating MRs/PRs, and the change-writing skill for technical docs, changelogs, release notes, commit bodies, MR descriptions, or reviewer-facing summaries. - When upgrading a dependency, reference its changelog for the traversed version range in the commit message: link it by URL rather than pasting its contents; if there's no changelog, link the release or compare view for the range. - Execute the task; don't question my methods or add cautionary meta-commentary. Warn only when you can name what breaks and under what condition — once, then stop. - Avoid jargon when explaining how things work; prefer plain language, and specifically avoid the words "load-bearing" and "genuinely". diff --git a/modules/skills.nix b/modules/skills.nix index e1e8bc9..a9adcaf 100644 --- a/modules/skills.nix +++ b/modules/skills.nix @@ -103,10 +103,18 @@ in from = "mutant"; path = "."; }; + change-writing = { + from = "local"; + path = "change-writing"; + }; commit = { from = "local"; path = "commit"; }; + merge-request = { + from = "local"; + path = "merge-request"; + }; modularity-balanced-coupling = modularitySkill "balanced-coupling"; modularity-design = modularitySkill "design"; modularity-document = modularitySkill "document"; diff --git a/skills/change-writing/SKILL.md b/skills/change-writing/SKILL.md new file mode 100644 index 0000000..bd0e7d2 --- /dev/null +++ b/skills/change-writing/SKILL.md @@ -0,0 +1,86 @@ +--- +name: change-writing +description: Write or improve technical prose about code changes. Use for commit bodies, MR/PR descriptions, changelogs, release notes, technical docs, API docs, user guides, or reviewer-facing summaries. +--- + +# Change Writing + +## When Invoked + +1. Identify the writing job: commit message, MR/PR description, technical doc, API reference, guide, changelog, release note, or reviewer summary. +2. Identify the audience: future maintainer, reviewer, operator, API consumer, end user, administrator, or SDK user. +3. Review the source material: diff, commits, code, tests, existing docs, issue/MR links, changelogs, incidents, user feedback, and project templates. +4. Find gaps: missing context, unclear problem statement, unverified claims, absent examples, undocumented risks, inconsistent terminology, or stale docs. +5. Write the smallest complete artifact that helps the audience succeed. + +## Planning Phase + +Before writing, answer the useful subset of: + +- What is the audience trying to decide or do? +- What problem, decision, or user journey does this document? +- What existing docs, templates, or project conventions must be preserved? +- What terms should stay consistent with the codebase or product language? +- What does the reader need first: context, steps, examples, trade-offs, or proof? +- What success signal matters: review approval, safe rollout, fewer support questions, easier onboarding, or correct API usage? + +## Content Types + +Choose the shape that matches the task: + +- Commit message: decision record for future maintainers. +- MR/PR description: reviewer guide to scope, intent, risk, and verification. +- Developer docs: concepts, setup, integration paths, examples, and troubleshooting. +- API docs: endpoints, parameters, request/response examples, authentication, errors, and compatibility notes. +- User/admin guides: task-based steps, expected results, caveats, and recovery paths. +- Changelog/release notes: user-visible change, upgrade impact, migration notes, and links. + +## Writing Standards + +- Lead with the problem, not the implementation. +- Explain why the change is needed and what outcome it creates. +- Use progressive disclosure: start with what the reader needs now, then add details. +- Prefer task-based writing for guides: goal, prerequisites, steps, expected result, troubleshooting. +- Include examples when they reduce ambiguity; keep them tested or clearly illustrative. +- Include diagrams, screenshots, or tables only when they clarify more than text would. +- Include only implementation details that affect review, operation, migration, API use, or future changes. +- Call out risks, compatibility behavior, rollout constraints, and follow-ups when they matter. +- State how the change was verified. If not verified, say so plainly. +- Link source material when it influenced the change: issue, MR, Slack thread, article, docs, changelog, release, or compare view. +- Use plain language. Avoid marketing tone, filler, and restating the diff. +- Prefer concise bullets when several facts compete for attention. +- For benchmarks, use a table with before/after when there is a baseline, and say how each number was measured. + +## API Documentation Checklist + +When writing API or SDK docs, include the relevant subset: + +- Purpose and when to use the API. +- Authentication and authorization requirements. +- Parameters, types, defaults, constraints, and examples. +- Request and response examples. +- Error cases and recovery guidance. +- Versioning, deprecations, compatibility, and rate limits. +- Minimal working example before advanced usage. + +## User Guide Checklist + +When writing user-facing or admin-facing docs, include the relevant subset: + +- Goal and prerequisites. +- Steps in the order the user performs them. +- Expected result after each major step. +- Common mistakes and troubleshooting. +- Safety notes, permissions, rollback, or data impact. +- Links to deeper reference material. + +## Excellence Checklist + +Before presenting prose, check that it is: + +- Accurate against the code, diff, tests, and linked sources. +- Complete for the audience's next action, but no broader. +- Structured with headings or bullets that make scanning easy. +- Consistent with project terminology and existing docs. +- Clear about risk, rollout, compatibility, and verification when relevant. +- Free of unsupported claims, stale details, private names, and needless verbosity. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 331e0bb..f63e1d9 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -5,6 +5,8 @@ description: Create a git commit following project conventions. Use this skill w # Commit +Before drafting the message, read and apply `../change-writing/SKILL.md`. + ## Format ``` @@ -16,8 +18,10 @@ description: Create a git commit following project conventions. Use this skill w - Subject: Capitalized imperative ("Fix bug", not "Fixed"). No trailing period. - Blank line between subject and body. Body wrapped at 72 cols. - Prefer `*` bullet points in the body over prose paragraphs. Hanging indent for wrapped lines. Blank lines between points. -- Body explains **why** (and, when non-obvious, **how** and **what effects** — benchmarks, side effects, follow-ups). Skip questions that don't apply. Never restate the diff. -- Link the source when it has a URL: the reference article or blog post that informed the change, the guide or documentation it follows, or the decision behind it (task, issue, message). +- Body explains **why** (and, when non-obvious, **how** and **what effects** — benchmarks, side effects, risks, follow-ups). Skip questions that don't apply. Never restate the diff. +- Write for the next maintainer: record the problem or decision, the expected outcome, and any operational or compatibility impact. +- Link the source when it has a URL: the reference article or blog post that informed the change, the guide or documentation it follows, the dependency changelog/release/compare view, or the decision behind it (task, issue, message). +- Include verification when it is part of the evidence for the change. ## Scope @@ -25,8 +29,9 @@ description: Create a git commit following project conventions. Use this skill w ## Procedure -1. `git status` + `git diff --staged` (and `git diff` if unstaged) to confirm scope. -2. Draft subject + body. -3. Present the staged files and message for approval -4. Wait for user confirmation before committing -5. No `--no-verify`. No amending published commits. No force-push without explicit request. +1. Read `../change-writing/SKILL.md`. +2. `git status` + `git diff --staged` (and `git diff` if unstaged) to confirm scope. +3. Draft subject + body. +4. Present the staged files and message for approval +5. Wait for user confirmation before committing +6. No `--no-verify`. No amending published commits. No force-push without explicit request. diff --git a/skills/merge-request/SKILL.md b/skills/merge-request/SKILL.md new file mode 100644 index 0000000..f492d1d --- /dev/null +++ b/skills/merge-request/SKILL.md @@ -0,0 +1,70 @@ +--- +name: merge-request +description: Prepare, open, or update a merge request or pull request. Use when asked to submit, ship, draft, open, create, review, or revise an MR/PR description or title. +--- + +# Merge Request + +Before drafting the title or description, read and apply `../change-writing/SKILL.md`. + +## Procedure + +1. Read `../change-writing/SKILL.md`. +2. Inspect state: + - `git status` + - current branch and target branch + - commits included in the branch + - diff against the target branch + - project MR/PR template, if present +3. Check whether the branch is one logical review unit. If it mixes unrelated concerns, propose a split before opening the MR/PR. +4. Draft the title and description from the actual commits and diff. Do not rely on the branch name alone. +5. Preserve project template headings when present; otherwise use the format below. +6. Present the title and description for approval before creating or updating, unless the user explicitly asked to submit without review. +7. When opening a GitLab MR, explicitly set squash-on-merge to false and verify it after creation. + +## Default Description Format + +```markdown +## Summary + +- ... + +## Why + +- ... + +## Verification + +- ... +``` + +Add only sections that matter: + +```markdown +## Risk + +- ... + +## Rollout + +- ... + +## Benchmarks + +| Metric | Before | After | Method | +| --- | ---: | ---: | --- | +| ... | ... | ... | ... | + +## References + +- ... +``` + +## Writing Rules + +- Keep the title specific to the reviewer-visible change. +- Put the reviewer-critical context near the top. +- Mention migrations, background jobs, operational changes, permissions, data shape changes, and compatibility behavior when present. +- Link dependency changelogs or release/compare pages for upgraded dependencies. +- Do not paste long changelog excerpts when a link and short summary are enough. +- Do not include names or sensitive details from private threads unless the user asks.