{"name":"audit-code-comments-prompt","description":"A prompt that checks code comments and docstrings against the code they describe - wrong parameters or return values, outdated references, stale TODOs, misleading claims, comments that only restate the code - and suggests a fix, rewrite or removal for each. Use when the user wants comments or docstrings verified, finds comment rot, or added docs before a review.","category":"coding-prompts","tags":["docs","code-review","quality"],"models":["any"],"proven":false,"passing_families":0,"model_testing":"Not yet model-tested; testing Jan 2027","url":"https://theskillvault.ai/skills/audit-code-comments-prompt","api_url":"https://theskillvault.ai/api/skills/audit-code-comments-prompt","raw_url":"https://theskillvault.ai/api/skills/audit-code-comments-prompt/raw","body":"# Audit code comments (prompt)\n\nA wrong comment is worse than no comment. People trust it, and it sends them the wrong way. This prompt checks every comment against the code it sits on and says what to fix, rewrite or delete.\n\n## When to use\n- You or an AI just wrote a lot of docstrings or comments and want them checked for accuracy.\n- Old code is full of comments and you suspect many no longer match.\n- Before a review, you want the comments added or changed in the diff checked.\n\n## When not to use\n- You want a README or user guide written. Use write-readme-prompt.\n- You want the code itself reviewed for bugs. Use review-code-prompt.\n- You want messy code tidied, including comments. Use turn-messy-diff-into-clean-code-prompt.\n\n## Steps\n1. Choose the scope: the comments changed in a diff, or a folder of older code.\n2. Paste the prompt below into your AI coding tool. Change the base branch or swap in the folder.\n3. Fix the critical issues first. A comment that states something false must change today.\n4. Apply the removals you agree with. Delete comments that only restate the code.\n5. Ask for rewrites of the rest one file at a time, and re-run the prompt on the result.\n\n## Prompt\n```text\nCheck the code comments and docstrings added or changed in this branch (git diff main...HEAD). Compare each one with the code it describes. Do not edit anything yet.\n\n1. Accuracy: do parameters, return values, types and thrown errors match the signature? Does the described behaviour match the logic? Do referenced functions, files and flags still exist? Are claimed edge cases and performance notes true?\n2. Completeness: are important assumptions, preconditions, side effects and error cases stated? Is the reason for a non-obvious choice explained?\n3. Value: does it explain why, not just what? Flag comments that repeat the code, describe a temporary state, or will go stale with the next likely change.\n4. Misleading parts: vague wording, old names from before a refactor, examples that no longer work, TODOs and FIXMEs that are already done.\n\nWrite for a new teammate reading this code a year from now.\nOutput:\n- Critical: comments that are false or misleading (file:line, problem, fix).\n- Improve: comments missing key context (file:line, what is missing, suggested wording).\n- Remove: comments that add nothing (file:line, reason).\n- Good examples worth copying, if any.\nGive suggested wording for each rewrite. Wait for my go-ahead before changing files.\n```\n\n## How to adapt\n- Auditing old code instead of a diff? Replace the git command with \"the comments in src/billing/\".\n- Have a doc style such as JSDoc, docstrings or rustdoc? Add \"follow