audit-stale-comments

Name: audit-stale-comments
Author: PaulRBerg

68stars3forks

How to install audit-stale-comments?

paulrberg/agent-skills/audit-stale-comments

$npx -y skills add PaulRBerg/agent-skills --skill audit-stale-comments

Installs into the current project.

Summary

Audit JavaScript, TypeScript, and Go comments for verified stale, orphaned, misleading, or redundant claims.

Files · 1

View on GitHub

SKILL.md

1	# Audit Stale Comments
2
3	Audit source comments against the code they describe. Report only confirmed mismatches and noise; do not edit files
4	unless the user separately asks for fixes.
5
6	## Scope
7
8	Accept zero or more file or directory paths. With no arguments, use the current repository root. Resolve every path from
9	the current working directory and report any path that cannot be read.
10
11	Discover JavaScript, JSX, TypeScript, TSX, and Go source files. By default exclude:
12
13	- tests, testdata, fixtures, snapshots, and stories;
14	- generated, vendor, dependency, coverage, cache, and build-output directories;
15	- minified JavaScript and generated Go files.
16
17	An explicitly named test file or test directory overrides only the test exclusion. Generated, vendored, minified, and
18	build-output files remain excluded unless the user explicitly requests them.
19
20	Use repository-aware discovery when available (`git ls-files` or `rg --files`) and preserve the user's path order. Do
21	not impose an arbitrary result cap.
22
23	## Analysis
24
25	Split discovered files into non-overlapping batches of about ten. Delegate independent batches to read-only subagents
26	when supported; otherwise inspect them directly. Continue useful work while delegated batches run.
27
28	For every line, block, and documentation comment, compare the claim with adjacent code, referenced symbols, callers,
29	configuration, and relevant repository history when current code alone is inconclusive. Classify only clear findings:
30
31	- `STALE`: describes behavior the code no longer has;
32	- `ORPHANED`: references a symbol, path, flag, or concept that no longer exists;
33	- `MISLEADING`: materially suggests behavior different from the implementation;
34	- `REDUNDANT`: merely narrates self-explanatory code and carries no intent, constraint, or context.
35
36	Do not report style preferences, imperfect wording, useful rationale, or uncertainty as findings.
37
38	### Behavior-Bearing Go Comments
39
40	Treat these as part of program behavior or required documentation, not ordinary prose:
41
42	- compiler and tool directives, including `//go:*`, `//line`, and `//nolint`;
43	- build constraints and their required placement;
44	- cgo preambles attached to `import "C"`;
45	- `go:embed` patterns and the declarations they populate;
46	- package comments and exported-symbol documentation;
47	- concurrency, ownership, locking, lifetime, and safety contracts.
48
49	Verify these against Go syntax, symbol use, and tooling semantics. Never mark one redundant merely because the adjacent
50	declaration is obvious.
51
52	## Verification
53
54	Aggregate and deduplicate candidate findings, then reopen every reported location. Confirm its current line number and
55	the implementation evidence that makes the comment wrong or unnecessary. Drop findings that cannot be verified. A clean
56	result is valid and should not be padded with low-confidence observations.
57
58	## Report
59
60	Return:
61
62	```markdown
63	### 🔎 Stale-comments audit — <finding count or clean>
64
65	\| Scope \| Files analyzed \| Confirmed \| Not reviewed \|
66	\| ------- \| -------------- \| --------- \| --------------- \|
67	\| <paths> \| <count> \| <count> \| <count or none> \|
68
69	### Findings
70
71	#### STALE
72
73	- path/to/file.ts:42 — <comment claim, contradictory evidence, and why it matters>
74
75	#### ORPHANED
76
77	#### MISLEADING
78
79	#### REDUNDANT
80
81	### ⚠️ Not reviewed
82
83	- <path and reason>
84	```
85
86	Omit empty category and not-reviewed sections. When no findings remain and every file was reviewed, lead with
87	`### ✅ Clean — no confirmed stale, orphaned, misleading, or redundant comments`. If files were not reviewed, lead with
88	`### ⚠️ Review incomplete — no confirmed findings in reviewed scope` instead. When fixes were requested and applied,
89	lead with `### ✅ Comments fixed — <count>`, then add `### 📦 Changed` and `### 🧪 Verification`; do not collapse a
90	write receipt into `Clean`. Keep classifier tokens, paths, line numbers, directives, and quoted comment text exact and
91	undecorated. Completion requires the exact scope, analyzed-file count, confirmed findings with current lines and
92	evidence, and any files that could not be reviewed.

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

audit-stale-comments

68stars3forks

View on GitHub

How to install audit-stale-comments?

paulrberg/agent-skills/audit-stale-comments

$npx -y skills add PaulRBerg/agent-skills --skill audit-stale-comments

Installs into the current project.

Summary

Audit JavaScript, TypeScript, and Go comments for verified stale, orphaned, misleading, or redundant claims.

Files · 1

View on GitHub

SKILL.md

1	# Audit Stale Comments
2
3	Audit source comments against the code they describe. Report only confirmed mismatches and noise; do not edit files
4	unless the user separately asks for fixes.
5
6	## Scope
7
8	Accept zero or more file or directory paths. With no arguments, use the current repository root. Resolve every path from
9	the current working directory and report any path that cannot be read.
10
11	Discover JavaScript, JSX, TypeScript, TSX, and Go source files. By default exclude:
12
13	- tests, testdata, fixtures, snapshots, and stories;
14	- generated, vendor, dependency, coverage, cache, and build-output directories;
15	- minified JavaScript and generated Go files.
16
17	An explicitly named test file or test directory overrides only the test exclusion. Generated, vendored, minified, and
18	build-output files remain excluded unless the user explicitly requests them.
19
20	Use repository-aware discovery when available (`git ls-files` or `rg --files`) and preserve the user's path order. Do
21	not impose an arbitrary result cap.
22
23	## Analysis
24
25	Split discovered files into non-overlapping batches of about ten. Delegate independent batches to read-only subagents
26	when supported; otherwise inspect them directly. Continue useful work while delegated batches run.
27
28	For every line, block, and documentation comment, compare the claim with adjacent code, referenced symbols, callers,
29	configuration, and relevant repository history when current code alone is inconclusive. Classify only clear findings:
30
31	- `STALE`: describes behavior the code no longer has;
32	- `ORPHANED`: references a symbol, path, flag, or concept that no longer exists;
33	- `MISLEADING`: materially suggests behavior different from the implementation;
34	- `REDUNDANT`: merely narrates self-explanatory code and carries no intent, constraint, or context.
35
36	Do not report style preferences, imperfect wording, useful rationale, or uncertainty as findings.
37
38	### Behavior-Bearing Go Comments
39
40	Treat these as part of program behavior or required documentation, not ordinary prose:
41
42	- compiler and tool directives, including `//go:*`, `//line`, and `//nolint`;
43	- build constraints and their required placement;
44	- cgo preambles attached to `import "C"`;
45	- `go:embed` patterns and the declarations they populate;
46	- package comments and exported-symbol documentation;
47	- concurrency, ownership, locking, lifetime, and safety contracts.
48
49	Verify these against Go syntax, symbol use, and tooling semantics. Never mark one redundant merely because the adjacent
50	declaration is obvious.
51
52	## Verification
53
54	Aggregate and deduplicate candidate findings, then reopen every reported location. Confirm its current line number and
55	the implementation evidence that makes the comment wrong or unnecessary. Drop findings that cannot be verified. A clean
56	result is valid and should not be padded with low-confidence observations.
57
58	## Report
59
60	Return:
61
62	```markdown
63	### 🔎 Stale-comments audit — <finding count or clean>
64
65	\| Scope \| Files analyzed \| Confirmed \| Not reviewed \|
66	\| ------- \| -------------- \| --------- \| --------------- \|
67	\| <paths> \| <count> \| <count> \| <count or none> \|
68
69	### Findings
70
71	#### STALE
72
73	- path/to/file.ts:42 — <comment claim, contradictory evidence, and why it matters>
74
75	#### ORPHANED
76
77	#### MISLEADING
78
79	#### REDUNDANT
80
81	### ⚠️ Not reviewed
82
83	- <path and reason>
84	```
85
86	Omit empty category and not-reviewed sections. When no findings remain and every file was reviewed, lead with
87	`### ✅ Clean — no confirmed stale, orphaned, misleading, or redundant comments`. If files were not reviewed, lead with
88	`### ⚠️ Review incomplete — no confirmed findings in reviewed scope` instead. When fixes were requested and applied,
89	lead with `### ✅ Comments fixed — <count>`, then add `### 📦 Changed` and `### 🧪 Verification`; do not collapse a
90	write receipt into `Clean`. Keep classifier tokens, paths, line numbers, directives, and quoted comment text exact and
91	undecorated. Completion requires the exact scope, analyzed-file count, confirmed findings with current lines and
92	evidence, and any files that could not be reviewed.

People who liked this also viewed

6 picks

Type