[AI-2214] Add authoring rules for comments, commits and PR descriptions

[Inok]

Closes #658 — AI-2214

What & why

kcap-server settled how comments, commit messages and PR descriptions are written. Here there was one line on comments and nothing on the other two, so agents copy what the tree shows — 1,705 comment lines carrying §2.7 B6, Round 2 Finding 2 or It used to be. The rules land verbatim: a Comments section (two-part test, Never list, three exceptions), a Commit messages section, and a PR template owning length, headings and its own Never list. Same wording in both repos, so an agent moving between them writes the same way in each.

Where to look

Three deltas, each forced by this repo:

• Both trackers are named once, on the description's reference line. Nothing else carries an id: the commit subject's reference is the GitHub issue, trailing (one clause (#123)), and the PR title carries none at all — squash-merge appends the PR number, so a second (#n) beside it reads as another PR.
• Comments exception 1 names the GitHub issue number — Linear ids are banned in comments here.
• The template's reference line is Closes #<issue> — AI-<id>, deliberately not a live reference: a specimen number would close an unrelated issue whenever the template shipped unedited.

### Area-specific pitfalls is not ported: it only introduced docs/gotchas/, absent here.

Verification

Ported sections diffed against the server's text: identical but for the CLAUDE.md deltas above; the template differs only by the reference line. Docs-only — no build.

[linear-code]

AI-2211

AI-2214

[qodo-code-review]

PR Summary by Qodo

Add authoring rules for comments, commits, and PR descriptions

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Document strict comment-writing rules with a two-part test, bans, and exceptions.
• Standardize commit message subjects/bodies to survive squash merges and avoid narration.
• Add a PR template enforcing headings, reference format, brevity, and evidence-based verification.

Diagram

graph TD
  A["Contributor"] --> B["CLAUDE.md rules"] --> C["Code comments"]
  A --> D["Commit message rules"] --> E["Commit messages"]
  A --> F["PR template"] --> G["PR description"]
  B --> G
  F --> D

  subgraph Legend
    direction LR
    _actor["Actor"] ~~~ _doc["Guidelines/Template"] ~~~ _artifact["Written artifact"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Move authoring rules into CONTRIBUTING.md

• ➕ More discoverable for humans browsing repository contribution docs
• ➕ Keeps CLAUDE.md focused on agent execution guidance
• ➖ Agents may not consult it by default unless explicitly wired into prompts
• ➖ Splits related guidance across multiple documents

2. Enforce via automation (PR lint / commit lint)

• ➕ Objective enforcement; reduces drift over time
• ➕ Catches violations before review
• ➖ Higher implementation/maintenance cost and false-positive risk
• ➖ Hard to lint nuanced content bans (historical narration, review artifacts) reliably

3. Use shorter guidance plus examples

• ➕ Lower cognitive load; faster onboarding
• ➕ Examples can clarify edge cases
• ➖ Less explicit “Never” boundaries; more room for interpretation
• ➖ Examples can become stale or be cargo-culted

Recommendation: The chosen approach (explicit rules in CLAUDE.md plus a PR template) is the best default for aligning both humans and agents without introducing brittle automation. If enforcement becomes necessary later, consider adding lightweight checks (e.g., headings present, reference line present) while leaving content nuance to review.

Files changed (2) +81 / -2

Documentation (1) +41 / -2

CLAUDE.mdDefine authoring rules for comments and commit messages; align PR guidance +41/-2

Define authoring rules for comments and commit messages; align PR guidance

• Adds a detailed 'Comments' section with a two-part usefulness test, a content ban list, and three explicit exceptions. Adds 'Commit messages' rules covering subject format, body constraints, and squash-merge survivability; updates PR guidance to reference the PR template and removes the title cleanliness clause while keeping references in the description.

CLAUDE.md

Other (1) +40 / -0

PULL_REQUEST_TEMPLATE.mdAdd PR body template with strict headings, length target, and bans +40/-0

Add PR body template with strict headings, length target, and bans

• Introduces a repository PR template that fixes the PR body structure to three headings and sets a 1,200-character target. Adds a required reference line convention and a 'Never' list to prevent historical narration, review artifacts, and unevidenced claims.

.github/PULL_REQUEST_TEMPLATE.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. PR title rule conflicts ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md says PRs must put the Linear+GitHub references in the description “not the title”, but
immediately prescribes a PR title format that includes the Linear id prefix ([AI-123]). This
contradiction will cause agents/contributors to either omit the [AI-*] prefix (breaking existing
documented convention) or violate the “not the title” rule.

Code

CLAUDE.md[R161-164]

+- **PRs must reference both the Linear issue and the GitHub issue.** Put these references in the PR *description*, not the title. Reference the GitHub issue with a closing keyword (e.g. `Closes #123`) and include the Linear issue (e.g. `AI-774`) so Linear links the PR back to the imported issue.
+
+Title: commit-subject rules — `[AI-123] Show "Copied" tooltip on clipboard copy`.
+

Evidence

The new bullet explicitly bans putting the references in the title, but the newly-added title rule
includes the [AI-123] prefix, and existing repo docs already instruct that PR titles use the
[AI-*] prefix.

CLAUDE.md[160-165]
docs/superpowers/plans/2026-05-10-ai-70-codex-hook-surface.md[23-26]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`CLAUDE.md` currently contradicts itself: it says to keep references out of the PR title, but then mandates a title format that embeds the Linear id (`[AI-123]`). This will produce inconsistent PR authoring and makes the guidance impossible to follow literally.

### Issue Context
The repo already documents PR titles using the `[AI-…]` prefix elsewhere, so the “not the title” wording likely intended to prohibit putting `Closes #123` (and/or the full reference line) in the title, not the `[AI-*]` prefix.

### Fix Focus Areas
- CLAUDE.md[160-165]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Template lacks reference line ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new PR template instructs authors to “Keep the reference line above the first heading” and
describes what it should contain, but the template does not actually include any non-comment
reference line placeholder. This makes the required reference easy to miss and contradicts the
template’s own instruction.

Code

.github/PULL_REQUEST_TEMPLATE.md[R8-10]

+Keep the reference line above the first heading — it is what links the PR to both
+trackers, and it is not part of the character target.
+

Evidence

The template mandates a reference line and explains its format, but the file content jumps directly
from the comment about the reference line to the first heading, with no actual reference line
present.

.github/PULL_REQUEST_TEMPLATE.md[8-28]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`.github/PULL_REQUEST_TEMPLATE.md` requires a reference line above the first heading, but provides only HTML comments describing it and no actual placeholder line to fill in. Authors will commonly leave the template as-is, resulting in PRs missing the required reference line.

### Issue Context
GitHub shows the template content in the PR body editor; a concrete placeholder (e.g. `Closes #123 — AI-123`) is the most reliable way to ensure the reference is present and edited.

### Fix Focus Areas
- .github/PULL_REQUEST_TEMPLATE.md[8-27]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can hide the parts of a finding you never read, like the evidence or the agent prompt

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗