---
name: sanitize-comments
description: Use when auditing source code comments and commit messages for AI methodology references, management language, or corporate attribution violations
version: "1.0"
owner: platform-governance
tier: full
source: .enterprise/governance/agent-skills/sanitize-comments/SKILL.md
quick: .enterprise/governance/agent-skills/sanitize-comments/SKILL-QUICK.md
portable: true
---

# 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.