From e5b54c24afdd569765b215732884bd0a8f2758a9 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Fri, 24 Apr 2026 19:11:41 -0500
Subject: 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.
---
 claude-rules/commits.md | 25 ++++++++++++++++++++-----
 claude-rules/testing.md |  4 ++++
 2 files changed, 24 insertions(+), 5 deletions(-)

(limited to 'claude-rules')

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.
-- 
cgit v1.2.3