# Audit Refactoring

> Run a single-session refactoring audit on the codebase

- Skill: `majiayu000/audit-refactoring-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/audit-refactoring-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/audit-refactoring-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/majiayu000/audit-refactoring-2

---


# Single-Session Refactoring Audit

## Pre-Audit Validation

**Step 0: Episodic Memory Search (Session #128)**

Before running refactoring audit, search for context from past sessions:

```javascript
// Search for past refactoring audit findings
mcp__plugin_episodic -
  memory_episodic -
  memory__search({
    query: ["refactoring audit", "god object", "complexity"],
    limit: 5,
  });

// Search for specific tech debt discussions
mcp__plugin_episodic -
  memory_episodic -
  memory__search({
    query: ["cognitive complexity", "duplicate code", "circular"],
    limit: 5,
  });
```

**Why this matters:**

- Compare against previous refactoring targets
- Identify recurring complexity hotspots (may need architectural fix)
- Track which files were flagged before and why
- Prevent re-flagging intentional design decisions

---

**Step 1: Check Thresholds**

Run `npm run review:check` and report results.

- If no thresholds triggered: "⚠️ No review thresholds triggered. Proceed
  anyway?"
- Continue with audit regardless (user invoked intentionally)

**Step 2: Gather Current Baselines**

Collect these metrics by running commands:

```bash
# SonarCloud issues (query via MCP or npm run sonar:report)
npm run sonar:report 2>/dev/null || echo "No SonarCloud data available"

# Circular dependencies
npm run deps:circular 2>&1

# Unused exports
npm run deps:unused 2>&1 | head -30

# Large files (potential god objects)
find app components lib -name "*.ts" -o -name "*.tsx" 2>/dev/null | xargs wc -l 2>/dev/null | sort -n | tail -20

# Duplicate code patterns
grep -rn "TODO\|FIXME\|HACK" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l
```

**Step 2b: Query SonarCloud for Cognitive Complexity (if MCP available)**

If `mcp__sonarcloud__get_issues` is available:

- Query with `types: "CODE_SMELL"` and `severities: "CRITICAL"` to get cognitive
  complexity violations
- These are the primary refactoring targets (47 CRITICAL as of 2026-01-05
  baseline)
- Compare current count against baseline - significant changes indicate code
  quality trends
- Use issue file paths to prioritize audit focus areas

This provides real-time cognitive complexity data for targeted refactoring.

**Step 3: Load False Positives Database**

Read `docs/audits/FALSE_POSITIVES.jsonl` and filter findings matching:

- Category: `refactoring`
- Expired entries (skip if `expires` date passed)

Note patterns to exclude from final findings.

**Step 4: Check Template Currency**

Read `docs/multi-ai-audit/templates/REFACTORING_AUDIT.md` and verify:

- [ ] SonarCloud baseline is current (778 issues, 47 CRITICAL)
- [ ] Known god objects are listed
- [ ] Batch fix opportunities are documented

If outdated, note discrepancies but proceed with current values.

---

## Audit Execution

**Focus Areas (5 Categories):**

1. God Objects (large files, too many responsibilities)
2. Code Duplication (repeated patterns, copy-paste code)
3. Cognitive Complexity (SonarCloud CRITICAL targets)
4. Architecture Violations (layer boundaries, import cycles)
5. Technical Debt Markers (TODOs, FIXMEs, HACKs)

**For each category:**

1. Search relevant files using Grep/Glob
2. Identify specific issues with file:line references
3. Classify severity: S0 (blocking) | S1 (major friction) | S2 (annoying) | S3
   (nice-to-have)
4. Estimate effort: E0 (trivial) | E1 (hours) | E2 (day) | E3 (major)
5. **Assign confidence level** (see Evidence Requirements below)

**Refactoring Targets:**

- Files > 300 lines (potential split candidates)
- Functions > 50 lines (complexity risk)
- Components with > 10 props (interface too large)
- Files with > 5 imports from different domains (coupling)
- Circular dependencies (from deps:circular)
- Unused exports (from deps:unused)

**Scope:**

- Include: `app/`, `components/`, `lib/`, `hooks/`, `functions/`
- Exclude: `node_modules/`, `.next/`, `docs/`

---

## Evidence Requirements (MANDATORY)

**All findings MUST include:**

1. **File:Line Reference** - Exact location (e.g., `lib/utils.ts:45`)
2. **Code Snippet or Metrics** - The actual problematic code or measured metrics
   (lines, complexity)
3. **Verification Method** - How you confirmed this is an issue (wc -l,
   deps:circular, grep)
4. **Quantified Impact** - Lines of code, number of dependencies, complexity
   score

**Confidence Levels:**

- **HIGH (90%+)**: Confirmed by tool (SonarCloud, deps:circular, wc -l),
  verified file exists, metrics match
- **MEDIUM (70-89%)**: Found via pattern search, file verified, but metrics
  estimated
- **LOW (<70%)**: Pattern match only, needs manual verification

**S0/S1 findings require:**

- HIGH or MEDIUM confidence (LOW confidence S0/S1 must be escalated)
- Dual-pass verification (re-read the code after initial finding)
- Cross-reference with SonarCloud or dependency analysis output

---

## Cross-Reference Validation

Before finalizing findings, cross-reference with:

1. **SonarCloud issues** - Mark findings as "TOOL_VALIDATED" if SonarCloud
   flagged same issue
2. **deps:circular output** - Mark architecture findings as "TOOL_VALIDATED" if
   tool detected cycle
3. **deps:unused output** - Mark dead code findings as "TOOL_VALIDATED" if tool
   detected unused export
4. **Prior audits** - Check `docs/audits/single-session/refactoring/` for
   duplicate findings

Findings without tool validation should note: `"cross_ref": "MANUAL_ONLY"`

---

## Dual-Pass Verification (S0/S1 Only)

For all S0 (blocking) and S1 (major friction) findings:

1. **First Pass**: Identify the issue, note file:line and initial evidence
2. **Second Pass**: Re-read the actual code in context
   - Verify the complexity/coupling issue is real
   - Check for intentional design decisions (documented trade-offs)
   - Confirm file and line still exist
3. **Decision**: Mark as CONFIRMED or DOWNGRADE (with reason)

Document dual-pass result in finding: `"verified": "DUAL_PASS_CONFIRMED"` or
`"verified": "DOWNGRADED_TO_S2"`

---

## Output Requirements

**1. Markdown Summary (display to user):**

```markdown
## Refactoring Audit - [DATE]

### Baselines

- SonarCloud CRITICAL: X issues
- Circular dependencies: X
- Unused exports: X
- Files > 300 lines: X
- TODO/FIXME/HACK markers: X

### Findings Summary

| Severity | Count | Category | Confidence  |
| -------- | ----- | -------- | ----------- |
| S0       | X     | ...      | HIGH/MEDIUM |
| S1       | X     | ...      | HIGH/MEDIUM |
| S2       | X     | ...      | ...         |
| S3       | X     | ...      | ...         |

### Top Refactoring Candidates

1. [file] - X lines, Y responsibilities (S1/E2) - DUAL_PASS_CONFIRMED
2. ...

### False Positives Filtered

- X findings excluded (matched FALSE_POSITIVES.jsonl patterns)

### Quick Wins (E0-E1)

- ...

### Batch Fix Opportunities

- X instances of [pattern] can be auto-fixed
- ...

### Recommendations

- ...
```

**2. JSONL Findings (save to file):**

Create file: `docs/audits/single-session/refactoring/audit-[YYYY-MM-DD].jsonl`

**CRITICAL - Use JSONL_SCHEMA_STANDARD.md format:**

```json
{
  "category": "refactoring",
  "title": "Short specific title",
  "fingerprint": "refactoring::path/to/file.ts::identifier",
  "severity": "S0|S1|S2|S3",
  "effort": "E0|E1|E2|E3",
  "confidence": 90,
  "files": ["path/to/file.ts:123"],
  "why_it_matters": "1-3 sentences explaining refactoring need",
  "suggested_fix": "Concrete refactoring direction",
  "acceptance_tests": ["Array of verification steps"],
  "evidence": ["code structure info", "wc -l output", "deps:circular output"],
  "symbols": ["ClassName", "functionName"],
  "duplication_cluster": {
    "is_cluster": true,
    "cluster_summary": "Pattern description",
    "instances": [{ "file": "path1.ts", "symbol": "name" }]
  }
}
```

**For S0/S1 findings, ALSO include verification_steps:**

```json
{
  "verification_steps": {
    "first_pass": {
      "method": "grep|tool_output|file_read|code_search",
      "evidence_collected": ["initial evidence"]
    },
    "second_pass": {
      "method": "contextual_review|exploitation_test|manual_verification",
      "confirmed": true,
      "notes": "Confirmation notes"
    },
    "tool_confirmation": {
      "tool": "sonarcloud|typescript|patterns_check|NONE",
      "reference": "Tool output or NONE justification"
    }
  }
}
```

**⚠️ REQUIRED FIELDS (per JSONL_SCHEMA_STANDARD.md):**

- `category` - MUST be `refactoring` (normalized from
  GodObject/Duplication/etc.)
- `fingerprint` - Format: `<category>::<primary_file>::<identifier>`
- `files` - Array with file paths (include line as `file.ts:123`)
- `confidence` - Number 0-100 (not string)
- `acceptance_tests` - Non-empty array of verification steps

**3. Markdown Report (save to file):**

Create file: `docs/audits/single-session/refactoring/audit-[YYYY-MM-DD].md`

Full markdown report with all findings, baselines, and refactoring plan.

---

## Post-Audit Validation

**Before finalizing the audit:**

1. **Run Validation Script:**

   ```bash
   node scripts/validate-audit.js docs/audits/single-session/refactoring/audit-[YYYY-MM-DD].jsonl
   ```

2. **Validation Checks:**
   - All findings have required fields
   - No matches in FALSE_POSITIVES.jsonl (or documented override)
   - No duplicate findings
   - All S0/S1 have HIGH or MEDIUM confidence
   - All S0/S1 have DUAL_PASS_CONFIRMED or TOOL_VALIDATED

3. **If validation fails:**
   - Review flagged findings
   - Fix or document exceptions
   - Re-run validation

---

## Post-Audit

1. Display summary to user
2. Confirm files saved to `docs/audits/single-session/refactoring/`
3. Run `node scripts/validate-audit.js` on the JSONL file
4. **Validate CANON schema** (if audit updates CANON files):
   ```bash
   npm run validate:canon
   ```
   Ensure all CANON files pass validation before committing.
5. **Update AUDIT_TRACKER.md** - Add entry to "Refactoring Audits" table:
   - Date: Today's date
   - Session: Current session number from SESSION_CONTEXT.md
   - Commits Covered: Number of commits since last refactoring audit
   - Files Covered: Number of files analyzed for refactoring
   - Findings: Total count (e.g., "1 S1, 3 S2, 5 S3")
   - Confidence: Overall confidence (HIGH if majority HIGH, else MEDIUM)
   - Validation: PASSED or PASSED_WITH_EXCEPTIONS
   - Reset Threshold: YES (single-session audits reset that category's
     threshold)
   - Run:
     `node scripts/reset-audit-triggers.js --type=single --category=refactoring --apply`
6. **TDMS Integration (MANDATORY)** - Ingest findings to canonical debt store:
   ```bash
   node scripts/debt/intake-audit.js docs/audits/single-session/refactoring/audit-[YYYY-MM-DD].jsonl --source "audit-refactoring-[DATE]"
   ```
   This assigns DEBT-XXXX IDs and adds to
   `docs/technical-debt/MASTER_DEBT.jsonl`. See
   `docs/technical-debt/PROCEDURE.md` for the full TDMS workflow.
7. Ask: "Would you like me to tackle any of these refactoring tasks now?
   (Recommend starting with batch fixes)"

---

## Threshold System

### Category-Specific Thresholds

This audit **resets the refactoring category threshold** in
`docs/AUDIT_TRACKER.md` (single-session audits reset their own category;
multi-AI audits reset all thresholds). Reset means the commit counter for this
category starts counting from zero after this audit.

**Refactoring audit triggers (check AUDIT_TRACKER.md):**

- 40+ commits since last refactoring audit, OR
- 3+ new complexity warnings, OR
- Circular dependency detected

### Multi-AI Escalation

Multi-AI audits are triggered by total commits or time elapsed (not single audit
counts). Check `npm run review:check` for current multi-AI trigger status.

---

## Adding New False Positives

If you encounter a pattern that should be excluded from future audits:

```bash
node scripts/add-false-positive.js \
  --pattern "regex-pattern" \
  --category "refactoring" \
  --reason "Explanation of why this is intentional complexity" \
  --source "AI_REVIEW_LEARNINGS_LOG.md#review-XXX"
```

---

## Documentation References

Before running this audit, review:

### TDMS Integration (Required)

- [PROCEDURE.md](docs/technical-debt/PROCEDURE.md) - Full TDMS workflow
- [MASTER_DEBT.jsonl](docs/technical-debt/MASTER_DEBT.jsonl) - Canonical debt
  store
- Intake command:
  `node scripts/debt/intake-audit.js <output.jsonl> --source "audit-refactoring-<date>"`

### Documentation Standards (Required)

- [JSONL_SCHEMA_STANDARD.md](docs/templates/JSONL_SCHEMA_STANDARD.md) - Output
  format requirements and TDMS field mapping
- [DOCUMENTATION_STANDARDS.md](docs/DOCUMENTATION_STANDARDS.md) - 5-tier doc
  hierarchy
- [CODE_PATTERNS.md](docs/agent_docs/CODE_PATTERNS.md) - Anti-patterns to check