aboutsummaryrefslogtreecommitdiff
path: root/claude-rules
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-04-24 19:11:41 -0500
committerCraig Jennings <c@cjennings.net>2026-04-24 19:11:41 -0500
commite5b54c24afdd569765b215732884bd0a8f2758a9 (patch)
tree7adda3a4d514b5259d4f75d0da24fdfdde9c1c77 /claude-rules
parent060636d2f9acc8c37bc5873f109ffa16c270f98a (diff)
downloadrulesets-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.md25
-rw-r--r--claude-rules/testing.md4
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.