Sanitize Comments — Full Policy

Full policy for removing methodology, management, and AI-attribution references
from source code comments. Complements commit-hygiene (which governs commit messages).

---

1. Scope

This skill operates only on:

• Inline comments (//, #, --, /* */)
• Docstrings / file-level block comments
• XML doc comments (/// <summary>)
• TSDoc / JSDoc (/** */)
• JavaDoc / DartDoc / GoDoc comments
• File header comments

Out of scope (do not touch):

• Executable code
• Variable/class/method names
• String literals
• Configuration values
• Test assertions

---

2. Removal Targets

2.1 Project Management Methodology

Remove any comment referencing:

Category	Examples
Requirement types	FR, NFR, AC, Acceptance Criteria, Functional Requirement
Agile artifacts	Epic, Story, User Story, Task, Subtask, Sprint, Backlog, Roadmap, Milestone
Tools	Jira, Azure DevOps, ADO, Linear, Shortcut, GitHub Issues
Identifiers	"Ticket #123", "Issue #…", "Work Item …", "Story PROJ-456"
Phrases	"Conforme requisito", "Atende ao FR-", "Relacionado à Story", "Implementado para a Feature", "Critério de aceite", "Parte do Épico"

2.2 AI Tool Attribution

Remove any comment attributing code origin or review to an AI tool:

Pattern	Examples
Product names (whole-word)	Claude, HSEOS, Copilot, ChatGPT, Cursor, Gemini, Codex, OpenAI, Anthropic
Phrases	"generated by AI", "AI-assisted", "suggested by Claude", "reviewed by Copilot"
Co-authorship in headers	"Co-authored with Claude", "with assistance from AI"
Process references	"via LLM", "prompt: …", "AI-generated this section"

Word-boundary rule: Match whole words only. Never flag domain, email, detail,
maintain, trail, curtail — they contain "ai" as a substring but are NOT violations.

---

3. Preservation Rules

3.1 Always Preserve

• Behavioral descriptions: "Calculates the total including taxes"
• Decision rationale: "Uses eager loading here to avoid N+1 — see ADR-042"
• Invariants: "Invariant: balance is always non-negative"
• Preconditions: "Requires: user must be authenticated"
• Flow documentation: "Orchestrates the payment settlement flow"
• Performance annotations: // HOT PATH, // WARM PATH
• Safety comments: "// NOT thread-safe — caller must hold lock"
• TODO/FIXME with technical context: "// TODO: replace with async version after Go 1.22"

3.2 Partial Preservation

When a comment mixes methodology and technical content, remove only the methodology part:

// Before:
// Validates the payment amount (AC-12: amount must be positive and <= account balance)

// After:
// Validates the payment amount: must be positive and <= account balance

// Before:
// FR-23: Implements idempotent order processing to prevent duplicate charges

// After:
// Implements idempotent order processing to prevent duplicate charges

---

4. Transformation Rules

Comment type	Action
Exclusively methodology/AI attribution	Remove entire comment
Mixed: methodology + technical	Remove methodology part, preserve technical part
Exclusively technical	Preserve unchanged
AI-attribution phrase embedded	Remove phrase, preserve remaining content

Never:

• Add replacement text ("removed for compliance" → do not add this)
• Paraphrase surviving content
• Change code structure to accommodate removed comments
• Add any new comment of any kind

---

5. Execution Report Format

For each file processed, output:

## File: src/domain/Payment/PaymentAggregate.cs

### Removed
- Line 12: "// Implements FR-23: idempotent processing" → kept: "// Implements idempotent processing to prevent duplicate charges"
- Line 45: "// Generated by Claude — review before ship" → removed entirely
- Line 67: "// Story PROJ-456: add retry logic" → removed entirely (no technical content)

### Preserved
- Line 8: class-level XML doc (technical behavior description)
- Line 23: "// HOT PATH — zero alloc required"
- Line 89: "// Uses optimistic concurrency — see ADR-031"

### Confirmation
No executable code was modified.

---

6. Corporate Rationale

This policy exists because:

1. IP and process confidentiality — methodology references reveal internal planning structures, sprint cadences, and tooling choices to anyone with repository access (clients, auditors, open-source mirrors).

2. AI attribution prohibition — corporate policy prohibits crediting AI tools in deliverable artifacts. Code is a professional deliverable. Attribution in comments implies the organization endorses or discloses its AI tooling decisions.

3. Clean commit history — repositories may be audited, mirrored, or open-sourced. Comments containing "Claude suggested this" or "AI-generated" create reputational and contractual risk.

4. False positive risk — naive AI-detection (substring "ai") would incorrectly flag domain, email, maintain. This policy requires whole-word matching to avoid developer friction.

Quick Mode

For low-context activation, load .enterprise/governance/agent-skills/sanitize-comments/SKILL-QUICK.md or QUICK.md first. Load this full skill for deep analysis, violation fixing, or formal review gates.