Scrub Issue and Pull Request References From Code, Comments, and Docstrings

[ptr727]

Issue and pull request references are pervasive in this repository's code, comments, and docstrings. The maintainer's instruction is that they never belong there. This issue records the rule that already says so, measures what has to come out, and answers why the rule did not hold, since the scrub is worth little if the same text comes back on the next change.

The rule

It exists, and it is stated once, in .agents/skills/comment-and-doc-style/SKILL.md, "Comments":

Applies to code and workflow (#) comments alike.

• Comment only when the code does not explain itself, or the logic is genuinely complex. Self-evident code needs no comment.
• State only the non-obvious why, for the human reading this project's code now. No cross-project references, no historic or design narrative, no rule citations. Governance lives in the fleet's own instruction set, not echoed inline.

An issue reference is the concrete form of two of those three bans at once. (#973) is historic narrative, and ptr727/Blog #110 is a cross-project reference as well.

What has to come out

Measured on the tree at d0e722f, matching a # followed by two to five digits on a word boundary:

Where	Lines
*.py	107
*.md	157
*.sh, *.ps1, *.yml, *.json	10

The Python side splits 70 references inside a string or docstring against 27 inside a # comment. The heaviest files are scripts/tests/test_handoff.py (27), scripts/tests/test_pr_review.py (22), scripts/pr_review.py (21), host-setup/agent-safety/claude/gh-write-guard.py (11), and spec/audit.py (8).

Why the rule did not hold

Four causes, each independently sufficient, listed strongest first.

1. The tree teaches the opposite of the rule, at scale. 107 references across twelve Python files is not an oversight, it is a house style. Anyone editing near scripts/pr_review.py, whose every constant carries a rationale block ending in an issue number, reads that as the convention and matches it, which is the correct instinct applied to the wrong exemplar. No amount of rule text competes with the surrounding file until the surrounding file changes, so the scrub is the fix and the rule text is only what stops the regrowth.

2. The rule bans the category and never names the instance. "No historic or design narrative" is an abstraction. A writer adding (#973) is not thinking "I am narrating design history", they are thinking "I am citing the evidence for this claim", which reads as rigor rather than as narrative. The rule never says that an issue number, a pull request number, or a commit reference is what that abstraction is made of, so it does not fire at the moment it is violated.

3. Nothing detects it. The prose gate carries thirteen rules and none of them reads a reference. The only rule that touches comments at all is comment-added, which gates comment growth rather than comment content, and the comments label that stands it down waves the whole diff through, references included. The rule's own text further puts the largest cluster out of reach: "A docstring is not a comment line", and 70 of the 107 Python references are in strings and docstrings.

4. The rule is two pointers deep and lives only in a skill. CODESTYLE.md "General" says comments philosophy lives in GOVERNANCE.md. GOVERNANCE.md "Documentation Style Conventions" has a ### Comments subsection whose entire content is "The full comment philosophy, what earns one, structure, capitalization, growth discipline, is in the comment-and-doc-style Skill referenced above." So a reader following the canonical docs reaches two stubs before any rule text, and the rule binds only where that skill actually loads. It did not load in the session that raised this.

The open question, which is the maintainer's

The rule's own scope line reads "Applies to code and workflow (#) comments alike". It does not reach Markdown, and comment-added excludes Markdown explicitly. The example that prompted this was a line in .agents/skills/pr-review-conduct/SKILL.md, which is a document rather than code, so it is outside the rule as written.

That makes the Markdown side a decision rather than a scrub:

• Some of the 157 Markdown references are plainly legitimate. TODO.md carries 34 and is a tracker, and reports/ is generated by spec/audit.py rather than authored.
• Some are the same defect the code side has, a rule or a skill citing the issue that produced it.

A scrub that treats those alike either deletes a tracker's reason for existing or leaves the defect in the files agents read most.

Suggested shape of the work

1. Decide the Markdown scope above.
2. Scrub the code side, replacing each reference with the constraint it was standing in for, or deleting the clause where the reference was the whole of its value.
3. Add the instance to the rule, so it names an issue, pull request, or commit reference as what the existing ban covers.
4. Consider a prose-gate rule that reads a reference in a comment, a docstring, and a string, since causes 1 and 3 together are what let this reach 107 lines.

Step 3 without steps 1 and 2 leaves the exemplar intact, and the tree wins that argument every time.

[ptr727]

Maintainer's answer on the Markdown scope

fair on markdown, skills and governance and related instructional content should be treated like code, so a strengthening of verbiage and cleanup is due

So the rule's scope line, "Applies to code and workflow (#) comments alike", is what is wrong rather than the Markdown being exempt. Instructional content is held to the same bar as code, and the cleanup covers it.

Correction to the counts above

The table above was measured against the working tree of the branch that raised this, which had already removed a reference and added prose. Measured against d0e722f, which is the merge base and the right baseline:

Where	Lines
*.py	107
*.md	160
*.json	6
*.yml	3
*.sh, *.ps1	2

The Markdown figure is 160 rather than 157. Nothing else moves.

The Markdown split, under that answer

Instructional, and therefore in scope for the scrub:

Lines	Where
50	docs/reusable-workflows.md (21), host-setup/agent-safety/** (14), docs/fleet-map.md (5), docs/host-setup.md (3), scripts/README.md (3), README.md (2), docs/content-import.md (1), docs/pr-reviewer-reference.md (1)
12	the skills trees: 4 in .agents/skills/ and the same 4 mirrored into .github/skills/ and .claude-plugin/fleet-skills/, in pr-review-conduct (2), agent-conduct (1), and session-handoff (1)
1	GOVERNANCE.md

That is 63 lines. The skills figure is 4 real edits rather than 12, since only .agents/skills/ is authored and scripts/build_dist.py regenerates the other two trees, and editing a generated copy by hand is its own defect.

Out of scope, because the reference is the content rather than a citation attached to it:

Lines	Where	Why
34	reports/**	generated by spec/audit.py, so no edit there survives the next run
34	TODO.md	a tracker, whose entries are the issues

Left for the scrub to judge, 29 lines across four files, each a dated record of work rather than an instruction: docs/token-efficiency-plan.md (21), docs/pr-reviewer-evaluation.md (5), docs/homelab-runner-selection-plan.md (2), docs/pre-commit-hooks-rollout.md (1). These read like trackers, and a reference in a plan naming what it tracks is not the defect this issue is about. Treat them as trackers unless one turns out to be giving instructions.

What the verbiage change has to say

The rule's scope line is the defect, so the fix is there rather than in a new rule beside it. Two edits:

1. Widen the scope from "code and workflow (#) comments" to include instructional content, naming the skills, the canonical instruction set, and the reference docs under docs/ and host-setup/, and excluding a generated tree and a tracker explicitly, since the exclusion is what stops a later reader scrubbing reports/ back out of spec/audit.py's reach.
2. Name the instance, per cause 2 above: say that an issue, pull request, or commit reference is what "historic or design narrative" is made of. The category alone did not fire, and naming the instance is the cheapest thing that makes it fire.

Cause 3 still stands after both: nothing detects any of this, and comment-added reads neither a docstring nor Markdown. A gate is step 4 of the original shape and is worth its own decision once the tree is clean, since a gate turned on over 170 existing violations only teaches people to reach for the escape.