Fix overly aggressive audit-docs comments

[AlexJSully]

The audit-docs skill/prompt was overly aggressive in its comment restating the obvious multiple times through in-code comments (like stating what a var does above if statements when not relevant to the if statement).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
portfolio	Ready	Preview	Aug 5, 2026 4:58pm

[Copilot]

Pull request overview

This PR refines the audit-docs prompt/skill guidance to avoid producing noisy in-code comments that restate obvious facts at usage sites, keeping documentation concentrated on declarations and genuinely non-obvious logic.

Changes:

• Tightens Phase 3 (in-code documentation audit) guidance to remove restating comments and avoid repeating declaration-level facts at usage sites.
• Extends the surface-auditor agent and the audit report template to detect and report usage-site comment duplication patterns.
• Aligns related guidance in .github/copilot-instructions.md and typescript-code-and-test-standards to reinforce “document facts once, at the declaration”.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.github/prompts/audit-docs.prompt.md	Updates Phase 3 rules to discourage restating/duplicated in-code comments and adds a “document once at declaration” rule.
.github/copilot-instructions.md	Adds “fact stated once at declaration” guidance to reduce usage-site comment repetition.
.claude/skills/typescript-code-and-test-standards/SKILL.md	Adds the same “document once at declaration” guidance to the TypeScript standards skill.
.claude/skills/audit-docs/SKILL.md	Mirrors the prompt’s Phase 3 updates inside the audit-docs skill.
.claude/skills/audit-docs/references/evidence-and-citation.md	Adds guidance that “provable” does not imply “worth writing everywhere”.
.claude/skills/audit-docs/assets/audit-report.template.md	Updates report template to include removal of repeated usage-site comments.
.claude/skills/audit-docs/agents/surface-auditor.md	Expands the agent to report comments repeated above usage sites and defines output format additions.