brownfield-score

/brownfield-score — Risk Score Breakdown

Purpose

Detailed risk scoring breakdown for a specific file. Shows all contributing factors and project comparison.

Trigger

• "Why is this file risky?"
• "Show me the risk breakdown for X"
• "How does X's risk score compare?"

Type: /brownfield-score <file-path>

---

Steps

1. Resolve the target file

If $ARGUMENTS is empty, use currently open file. Resolve relative paths to project root. Verify file exists in graph.

2. Load file risk data from DB

const queries = require('./.claude/query-helpers.js');
const fileSummary = queries.getFileSummary(targetFilePath);

Returns all contributing factors:

• riskScore (final 0-100 score), band
• bugFixCommits, totalCommits
• ageInDays (days since creation)
• importedByCount (fan-in)
• importCount (fan-out)
• hasTests (boolean)
• isCircularDep (boolean)

3. Compute the score formula

Use the risk scoring algorithm (from graph.js):

riskScore = min(100, 
  (min(importedByCount, 50) * 1.2)
  + (isPublicContract ? 25 : 0)
  + ((100 - testCoverage) * 0.15)
)

Break this down visually for the dev.

4. Determine the band

• 0-30: Safe
• 31-60: Moderate
• 61-79: Risky
• 80-100: Critical

5. Compare to project average

Read all risk scores from dep-graph.json. Compute the median and average.

Example: "This file scores 72 (Risky). Project average is 45 (Moderate). This is in the top 15% most risky."

6. Build the scorecard

Format:

# Risk Score — <file-path>

## Overall Score

**72 / 100** — RISKY ⚠️

This file is in the top 15% most risky files in the project.
Project average: 45 (Moderate)
Project median: 38 (Moderate)

---

## Contributing Factors

| Factor | Value | Weight | Impact |
|--------|-------|--------|--------|
| Files importing this | 18 | ×1.2 | 21.6 pts |
| Public contract | Yes | +25 | 25 pts |
| Missing test coverage | 40% | ×0.15 | 9 pts |
| Recent bug fixes | 4 | - | Flagged ⚠️ |
| Age | 800 days | - | Old, many changes |
| **TOTAL** | | | **72** |

---

## What This Means

### High fan-in (18 files depend on this)
Changes here affect <N> files. You cannot change the public API without coordinating with dependents.

### Low test coverage (40%)
Only 40% of this file is tested. Changes are risky.

### Recent bug fixes (4 in last 6 months)
This file is fragile. Has had bugs before.

### Old file (800 days)
Lots of history. Many people have touched it. Potential for hidden assumptions.

---

## Recommendation

**Before editing this file:**
1. Add tests for the code you're changing (current coverage is below project average of 65%)
2. Check all dependents in the dependency graph
3. Run full test suite — not just unit tests
4. Get code review from whoever last edited this file

**If you need to change the public API:**
- Notify all 18 dependent file owners
- Use a deprecation period (add `@deprecated` comment)
- Update all dependents in the same PR

---

## Comparison

| File | Score | Reason |
|------|-------|--------|
| <high-risk-file> | 88 | Core infrastructure, many dependents |
| **<this-file>** | **72** | **Your file** |
| <moderate-file> | 45 | Utility, lower impact |

Your file is riskier than <moderate-file> because it has higher fan-in.
Your file is safer than <high-risk-file> because it's not core infrastructure.