diff options
| author | Craig Jennings <c@cjennings.net> | 2026-04-24 19:11:41 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-04-24 19:11:41 -0500 |
| commit | e5b54c24afdd569765b215732884bd0a8f2758a9 (patch) | |
| tree | 7adda3a4d514b5259d4f75d0da24fdfdde9c1c77 /claude-rules | |
| parent | 060636d2f9acc8c37bc5873f109ffa16c270f98a (diff) | |
| download | rulesets-e5b54c24afdd569765b215732884bd0a8f2758a9.tar.gz rulesets-e5b54c24afdd569765b215732884bd0a8f2758a9.zip | |
docs: split Linear vs PR structure; propagate content-scope rule to Tier 1 skills
Linear ticket bodies are now Problem + Fix only. PR descriptions keep
the four-section format (Problem, Fix, Why this fixes it, How it was
tested). Linear's GitHub integration handles the cross-link via the
PR body's Linear: line.
Cross-ref to the content-scope rule appended at the end of each Tier 1
skill that produces public artifacts: testing.md, arch-document,
arch-decide, arch-design, review-code, respond-to-review, brainstorm,
codify. Single-source the rule in commits.md, point at it from each
output-producing skill.
Diffstat (limited to 'claude-rules')
| -rw-r--r-- | claude-rules/commits.md | 25 | ||||
| -rw-r--r-- | claude-rules/testing.md | 4 |
2 files changed, 24 insertions, 5 deletions
diff --git a/claude-rules/commits.md b/claude-rules/commits.md index 7fcd4ba..876677d 100644 --- a/claude-rules/commits.md +++ b/claude-rules/commits.md @@ -98,15 +98,30 @@ project. Don't mention: Rule of thumb: if a teammate couldn't find the referenced thing without the user's help, don't reference it. -Structure shipped-fix descriptions in this order, using the headings -verbatim: +Different artifact types carry different content. Don't duplicate. + +**Linear ticket bodies:** two sections, in order. 1. **Problem** — what's wrong, with enough detail that a teammate can recognize the same failure mode in their own work. -2. **Fix** — what changed. +2. **Fix** — what changed (or what's proposed). + +The causal "why" and the test verification belong in the PR, not the +ticket. Linear's GitHub integration auto-cross-links once the PR body +includes the `Linear:` line, so the ticket reader reaches the PR +without needing a body-level link. + +**PR descriptions:** four sections, in order. Same first two as the +ticket, plus: + 3. **Why this fixes it** — causal link, one or two sentences. -4. **How it was tested** — skip for proposals, specs, or discussions. - Required for shipped fixes. +4. **How it was tested** — skip for proposals, specs, or discussions; + required for shipped fixes. + +The PR is the technical artifact. It carries the detail. + +**PR review comments** are conversational and don't follow this +structure — they follow the Voice and Focus rules above. Verbose preambles, motivational language, and context unrelated to the problem belong out. Same conciseness pressure as commit-message bodies. diff --git a/claude-rules/testing.md b/claude-rules/testing.md index b91b76c..02c6ce0 100644 --- a/claude-rules/testing.md +++ b/claude-rules/testing.md @@ -275,3 +275,7 @@ If you catch yourself thinking any of these, stop and write the test. - Non-deterministic tests (random without seed, network in unit tests) - Testing framework behavior instead of your code - Ignoring or skipping failing tests without a tracking issue + +## Content scope + +Test code, fixtures, docstrings, and comments are checked into the repo and visible to the team. They must follow the *Content scope for public artifacts* rule in [`commits.md`](commits.md): no local paths, no private repo names, no personal tooling references. |
