Best Practices

---
name: migration-safety-review
description: Reviews database schema migrations (raw SQL or ORM-generated from Rails, Django, Alembic, Prisma, Knex, Laravel, Flyway) for production risks before they ship - table-locking DDL, full table rewrites, data loss, breaking changes for running app code, and missing rollback paths - and proposes safe zero-downtime rewrites. Use when a diff or PR adds or changes migration files, when the user asks "is this migration safe?", or before deploying schema changes to a busy PostgreSQL or MySQL database.
---

# Migration Safety Review

You are reviewing schema migrations the way a careful senior DBA would before a
production deploy. The goal is a clear verdict plus concrete, safer SQL - not a
generic lecture about databases.

## Files in this skill

- `scripts/scan_migration.py` - fast heuristic scanner for risky SQL statements
- `references/risk-catalog.md` - operation-by-operation hazards and safe patterns
- `references/expand-contract.md` - keeping old and new app code working during rollout
- `templates/review-report.md` - the report format you must produce
- `examples/example-review.md` - a complete worked review to calibrate tone and depth

## Workflow

### 1. Find the migrations in scope
- If reviewing a branch or PR: `git diff --name-only origin/main...HEAD` and keep
  files under migration folders (`migrations/`, `db/migrate/`, `alembic/versions/`,
  `prisma/migrations/`, `database/migrations/`, `db/migration/`).
- Otherwise use the files or SQL the user pointed to.
- Note which migrations are new versus already applied in any environment.
  Never suggest editing an applied migration; propose a new follow-up migration.

### 2. Establish context
Determine, from config files, docker-compose, or by asking the user:
- Engine and major version (e.g. PostgreSQL 15, MySQL 8.0). Lock behavior depends on it.
- Approximate size and write traffic of each touched table.
- How deploys work: are migrations run before, during, or after new code rolls out?

If size or traffic is unknown, assume the table is large and hot, and say so.

### 3. Get the real SQL
ORM code hides what actually runs. Render the SQL first:

| Framework | Command |
|-----------|---------|
| Django | `python manage.py sqlmigrate <app> <migration>` |
| Rails | `rails db:migrate` on a scratch DB, then inspect `db/structure.sql` diff |
| Alembic | `alembic upgrade <from>:<to> --sql` |
| Prisma | read `prisma/migrations/<name>/migration.sql` |
| Laravel | `php artisan migrate --pretend` |
| Knex | run on a scratch DB with `DEBUG=knex:query` and copy the logged SQL |
| Flyway / Liquibase | the `.sql` file or `liquibase update-sql` |

Save rendered SQL to a temp file if it is not already a `.sql` file.

### 4. Run the scanner
```bash
python3 scripts/scan_migration.py --dialect postgres path/to/migration.sql
python3 scripts/scan_migration.py --dialect mysql db/*.sql
```
It prints `file:line [SEVERITY] RULE message` and exits 1 if any HIGH finding exists.
Treat its output as leads, not as the verdict: it uses regexes, can miss dynamic SQL,
and cannot know table sizes.

### 5. Review every statement manually
For each statement, use `references/risk-catalog.md` to answer:
1. What lock does it take, and for how long (instant, table scan, or full rewrite)?
2. Can it lose or corrupt data? Is that intended and backed up?
3. Will it queue behind long transactions? Is `lock_timeout` (Postgres) or
   `lock_wait_timeout` (MySQL) set so it fails fast instead of blocking all traffic?
4. Does it run in a transaction where it must not (e.g. `CREATE INDEX CONCURRENTLY`)?
5. Are large data backfills batched and separated from DDL?

### 6. Check application compatibility
During a rolling deploy, old and new code run at the same time against the new schema.
Follow `references/expand-contract.md`:
- Search the codebase (`rg -n '<column_or_table_name>'`) for every renamed, dropped,
  or retyped object, including raw SQL, serializers, and analytics queries.
- Flag any change the currently deployed code cannot tolerate.

### 7. Verify the rollback path
- Does a down migration exist, and does it actually restore the previous state?
- Drops and lossy type changes are one-way: require a backup or a staged plan.

### 8. Write the report
Fill in `templates/review-report.md` exactly. Match the depth of
`examples/example-review.md`. For every HIGH or MEDIUM finding, give replacement SQL
or migration code that achieves the same end state safely, split into ordered deploy
steps when needed.

## Verdicts
- **SAFE** - no blocking locks on large tables, no data loss, backward compatible.
- **SAFE WITH CHANGES** - can ship once the listed rewrites are applied.
- **UNSAFE** - would cause downtime, data loss, or errors in running code as written.

## Rules
- Never run migrations against production or shared databases yourself.
- Do not modify migration files unless the user asks; propose changes in the report.
- Be specific: name the table, the lock, and the failure mode. Skip generic advice.
- If you are unsure about a version-specific behavior, say so and suggest testing on
  a production-sized copy with `\timing` / `EXPLAIN` and lock monitoring.
FILE:references/risk-catalog.md
# Risk Catalog: Common Migration Operations

Lock names are PostgreSQL. ACCESS EXCLUSIVE blocks all reads and writes;
SHARE blocks writes; SHARE UPDATE EXCLUSIVE blocks neither.

## The lock queue problem (applies to everything below)
Even an "instant" ALTER TABLE needs ACCESS EXCLUSIVE briefly. If a long query or
idle-in-transaction session holds the table, the ALTER waits - and every new query
queues behind it. A 1 ms change can cause a multi-minute outage.
Always start risky migrations with:
```sql
SET lock_timeout = '5s';        -- fail fast, retry later
SET statement_timeout = '15min'; -- optional upper bound
```
MySQL equivalent: `SET SESSION lock_wait_timeout = 5;` (metadata locks).

## PostgreSQL operations

| Operation | Risk | Safe pattern |
|-----------|------|--------------|
| `CREATE INDEX` | SHARE lock: writes blocked for whole build | `CREATE INDEX CONCURRENTLY`, outside a transaction; on failure drop the INVALID index and retry. Rails: `disable_ddl_transaction!`; Django: `atomic = False` |
| `DROP INDEX` | ACCESS EXCLUSIVE | `DROP INDEX CONCURRENTLY` |
| `ADD COLUMN` nullable, no default | Instant | Safe (still set lock_timeout) |
| `ADD COLUMN ... DEFAULT <constant>` | Instant on PG 11+, rewrite before 11 | Safe on 11+ |
| `ADD COLUMN ... DEFAULT now()/random()/gen_random_uuid()` | Volatile default: full table rewrite | Add nullable column, backfill in batches, then set default |
| `ADD COLUMN ... NOT NULL` without default | Fails on non-empty table | Add nullable, backfill, then enforce NOT NULL (below) |
| `ALTER COLUMN ... SET NOT NULL` | Full scan under ACCESS EXCLUSIVE | `ADD CONSTRAINT c CHECK (col IS NOT NULL) NOT VALID`; `VALIDATE CONSTRAINT c`; then `SET NOT NULL` (PG 12+ skips the scan); drop `c` |
| `ALTER COLUMN ... TYPE` | Usually full rewrite + index rebuild under ACCESS EXCLUSIVE | Safe only if binary-coercible (varchar(n) to larger n or to text). Otherwise new column + dual write + backfill + swap |
| `ADD FOREIGN KEY` | Locks both tables while validating all rows | `ADD CONSTRAINT ... NOT VALID`, then `VALIDATE CONSTRAINT` in a separate step |
| `ADD CHECK` | Scan under ACCESS EXCLUSIVE | Same NOT VALID + VALIDATE pattern |
| `ADD UNIQUE` / `ADD PRIMARY KEY` | Builds index under lock | `CREATE UNIQUE INDEX CONCURRENTLY idx ...`; then `ADD CONSTRAINT ... UNIQUE USING INDEX idx` |
| `RENAME COLUMN` / `RENAME TO` | Instant, but breaks running code | Expand/contract (see expand-contract.md) |
| `DROP COLUMN` | Instant, but irreversible; old code selecting it errors | Remove all code references and deploy first; then drop |
| `DROP TABLE` / `TRUNCATE` | Irreversible data loss | Confirm backup and zero readers; consider renaming to `_deprecated` first |
| `ALTER TYPE ... ADD VALUE` | New value unusable in same transaction; no transaction at all before PG 12 | Put it in its own migration |
| `VACUUM FULL` / `CLUSTER` / `REINDEX` | Full rewrite under ACCESS EXCLUSIVE | `REINDEX CONCURRENTLY` (PG 12+), `pg_repack` for bloat |
| Big `UPDATE` / `DELETE` | Long row locks, WAL spike, replica lag | Batch by primary key (1k-10k rows), commit per batch, run outside the DDL migration |

## MySQL 8.0 (InnoDB) notes
- Always state the algorithm so MySQL errors instead of silently copying the table:
  `ALTER TABLE t ADD COLUMN c INT, ALGORITHM=INSTANT;` or
  `ALTER TABLE t ADD INDEX i (c), ALGORITHM=INPLACE, LOCK=NONE;`
- `ADD COLUMN` is INSTANT on 8.0.12+ (last position) and 8.0.29+ (any position).
- `MODIFY` / `CHANGE COLUMN` type changes use ALGORITHM=COPY: writes blocked.
- For large tables with COPY-only changes use `gh-ost` or `pt-online-schema-change`.
- DDL is not transactional in MySQL: a failed multi-statement migration leaves
  the schema half-applied. Keep one DDL statement per migration.
FILE:references/expand-contract.md
# Expand / Contract: Backward-Compatible Schema Changes

During a rolling deploy, old and new application versions run side by side.
If migrations run before the new code is live, the old code must work with the
new schema. If they run after, the new code must work with the old schema.
Expand/contract makes every step compatible with both.

## The three phases
1. **Expand** - add new structures only (columns, tables, indexes). Nothing is
   removed or renamed. Old code ignores the additions.
2. **Migrate** - deploy code that writes to both old and new structures, backfill
   existing rows in batches, then switch reads to the new structure.
3. **Contract** - once no deployed code touches the old structure, drop it in a
   separate, later migration.

Each phase is its own deploy. Never combine expand and contract in one migration.

## Recipes

### Rename a column (`users.name` to `users.full_name`)
1. Migration: add nullable `full_name`.
2. Code: write both `name` and `full_name`; read `name`.
3. Backfill `full_name = name` in batches where `full_name IS NULL`.
4. Code: read `full_name`; keep writing both.
5. Code: stop writing `name`. (Rails: add `name` to `ignored_columns` here.)
6. Migration: drop `name`.

### Change a column type (`orders.amount` int to numeric)
Same as rename: add `amount_numeric`, dual write, backfill, switch reads, drop old.
A trigger can handle dual writes if application changes are hard.

### Make a column NOT NULL
1. Code: always write a value.
2. Backfill NULL rows in batches.
3. Migration: CHECK ... NOT VALID, VALIDATE, SET NOT NULL (see risk-catalog.md).

### Drop a column or table
1. Code: remove every read and write (search ORM models, raw SQL, views,
   reports, ETL jobs, and other services sharing the database).
2. Deploy and wait at least one full release cycle.
3. Migration: drop. Take a backup or snapshot of the data first if it matters.

### Split or move a table
Create the new table, dual write, backfill, switch reads, stop old writes, drop.

## Compatibility questions to answer for each change
- Does any deployed code `SELECT *` or map all columns (ORMs often cache the
  column list at boot and fail when one disappears)?
- Does an insert from old code fail because a new column is NOT NULL without default?
- Do other services, cron jobs, BI dashboards, or replicas read this table?
- Can the deploy be rolled back to the previous code version without a down migration?

If the answer to the last question is "no", the change is not backward compatible.
FILE:templates/review-report.md
# Migration Safety Review: <migration name or PR title>

**Verdict:** SAFE | SAFE WITH CHANGES | UNSAFE
**Engine:** <e.g. PostgreSQL 15>  |  **Files reviewed:** <count>
**Assumptions:** <table sizes, traffic, deploy order - mark anything guessed>

## Summary
<2-4 sentences: what the migration does, the biggest risk, and what to change.>

## Findings

| # | Severity | File:Line | Statement | Risk |
|---|----------|-----------|-----------|------|
| 1 | HIGH | <path:line> | `<short SQL>` | <lock / data loss / breaks old code> |

### 1. <Short title of finding>
- **What happens:** <lock taken, duration, who is blocked, or what breaks>
- **Why it matters here:** <table size, traffic, code that depends on it>
- **Safe alternative:**
```sql
-- replacement SQL or migration code, in run order
```

<Repeat for each HIGH and MEDIUM finding. Group LOW findings in one list.>

## Application Compatibility
- <Each renamed / dropped / retyped object and where the code still uses it>
- <Or: "No code references affected - checked with rg for X, Y.">

## Rollback Plan
- <Does the down migration restore state? What is irreversible?>
- <Backup or snapshot required before running: yes/no>

## Recommended Deploy Sequence
1. <Migration or code deploy step>
2. <...>

## Scanner Output
```
<paste scripts/scan_migration.py output, or note false positives>
```
FILE:examples/example-review.md
# Example Review

**Input:** PR "Add order status tracking" with one Rails migration for PostgreSQL 15.
`orders` has ~40M rows and receives constant writes. Migrations run before new code.

```sql
-- rendered from db/migrate/20261002_add_status_to_orders.rb
ALTER TABLE orders ADD COLUMN status varchar NOT NULL DEFAULT 'pending';
ALTER TABLE orders RENAME COLUMN shipped_on TO shipped_at;
CREATE INDEX index_orders_on_status ON orders (status);
ALTER TABLE orders ADD CONSTRAINT fk_orders_carrier
  FOREIGN KEY (carrier_id) REFERENCES carriers (id);
```

**Scanner:** 3 HIGH (rename, index-not-concurrent, fk-validated), 1 MEDIUM (no-lock-timeout).

---

# Migration Safety Review: Add order status tracking

**Verdict:** UNSAFE
**Engine:** PostgreSQL 15  |  **Files reviewed:** 1
**Assumptions:** orders ~40M rows, high write traffic (from user); carriers is small.

## Summary
Adds an order status column, renames `shipped_on`, indexes status, and adds a carrier
foreign key. The status column itself is safe on PG 15, but the rename will break the
running app, and the index and FK will block writes on `orders` for minutes.
Split into three migrations and use concurrent / NOT VALID variants.

## Findings

| # | Severity | File:Line | Statement | Risk |
|---|----------|-----------|-----------|------|
| 1 | HIGH | rendered.sql:3 | `RENAME COLUMN shipped_on` | Old code errors on deploy |
| 2 | HIGH | rendered.sql:4 | `CREATE INDEX ... (status)` | Writes blocked during build |
| 3 | HIGH | rendered.sql:5 | `ADD ... FOREIGN KEY` | Full validation scan under lock |
| 4 | MEDIUM | rendered.sql:1 | no `lock_timeout` | ALTERs can queue and stall traffic |

### 1. Column rename breaks running code
- **What happens:** the rename is instant, but app servers still on the old release
  query `shipped_on` and fail with `column does not exist` until the deploy finishes.
- **Why it matters here:** `rg -n shipped_on` finds 7 references, including
  `app/serializers/order_serializer.rb` and the nightly `reports/fulfillment.sql`.
- **Safe alternative:** expand/contract. Add `shipped_at`, dual write, backfill in
  batches, switch reads, then drop `shipped_on` in a later release.

### 2. Index build blocks writes
- **Safe alternative** (separate migration, `disable_ddl_transaction!`):
```sql
CREATE INDEX CONCURRENTLY index_orders_on_status ON orders (status);
```

### 3. Foreign key validates 40M rows under lock
- **Safe alternative:**
```sql
SET lock_timeout = '5s';
ALTER TABLE orders ADD CONSTRAINT fk_orders_carrier
  FOREIGN KEY (carrier_id) REFERENCES carriers (id) NOT VALID;
-- next migration (takes only SHARE UPDATE EXCLUSIVE on orders):
ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_carrier;
```

**LOW:** none. Note `ADD COLUMN ... DEFAULT 'pending'` is metadata-only on PG 11+.

## Application Compatibility
- `shipped_on`: 7 code references plus one SQL report; must stay until contract phase.

## Rollback Plan
- Down migration drops `status` (data loss acceptable: new column). Rename is reversible.
- No backup required for this change set once the rename is removed.

## Recommended Deploy Sequence
1. Migration A: `SET lock_timeout`; add `status`; add `shipped_at`; add FK NOT VALID.
2. Migration B (no transaction): create status index concurrently.
3. Migration C: validate FK. Deploy code that dual writes `shipped_on`/`shipped_at`.
4. Backfill `shipped_at`; switch reads; later release drops `shipped_on`.
FILE:scripts/scan_migration.py
#!/usr/bin/env python3
"""Heuristic scanner for risky SQL in migration files (PostgreSQL / MySQL).
Usage: python3 scan_migration.py [--dialect postgres|mysql] FILE [FILE ...]
Exit codes: 0 = no HIGH findings, 1 = HIGH findings, 2 = usage error."""
import re, sys

F = re.I | re.S
COLDEF = r"(?:\([^)]*\)|[^,(])*"  # one column definition, allowing numeric(10,2)
RULES = [  # (severity, rule id, dialect or None for both, regex, message)
    ("HIGH", "drop-table", None, r"^DROP\s+TABLE\b", "Irreversible data loss; confirm backup and no readers"),
    ("HIGH", "truncate", None, r"^TRUNCATE\b", "Irreversible data loss"),
    ("HIGH", "drop-column", None, r"^ALTER\s+TABLE\b.*\bDROP\s+(COLUMN\b|(?!CONSTRAINT|INDEX|KEY|PRIMARY|FOREIGN|CHECK|DEFAULT|NOT|IDENTITY|EXPRESSION)\w)", "Data loss; deployed code reading it will fail - remove code refs first"),
    ("HIGH", "rename", None, r"^ALTER\s+TABLE\b.*\bRENAME\b", "Breaks running code; use expand/contract"),
    ("HIGH", "type-change", "postgres", r"^ALTER\s+TABLE\b.*\bALTER\s+(COLUMN\s+)?\S+\s+(SET\s+DATA\s+)?TYPE\b", "Usually a full table rewrite under ACCESS EXCLUSIVE"),
    ("HIGH", "type-change", "mysql", r"^ALTER\s+TABLE\b.*\b(MODIFY|CHANGE)\s+(COLUMN\s+)?\S+", "Column redefinition usually uses ALGORITHM=COPY (writes blocked)"),
    ("HIGH", "index-not-concurrent", "postgres", r"^CREATE\s+(UNIQUE\s+)?INDEX\s+(?!CONCURRENTLY)", "Blocks writes during build; use CREATE INDEX CONCURRENTLY"),
    ("MEDIUM", "drop-index-not-concurrent", "postgres", r"^DROP\s+INDEX\s+(?!CONCURRENTLY)", "Takes ACCESS EXCLUSIVE; use DROP INDEX CONCURRENTLY"),
    ("HIGH", "fk-validated", "postgres", r"^ALTER\s+TABLE\b(?!.*\bNOT\s+VALID\b).*\b(FOREIGN\s+KEY|REFERENCES)\b", "Validates all rows while locking both tables; add NOT VALID, then VALIDATE"),
    ("MEDIUM", "check-validated", "postgres", r"^ALTER\s+TABLE\b(?!.*\bNOT\s+VALID\b).*\bADD\s+(CONSTRAINT\s+\S+\s+)?CHECK\b", "Full scan under lock; add NOT VALID, then VALIDATE"),
    ("MEDIUM", "set-not-null", "postgres", r"\bSET\s+NOT\s+NULL\b", "Full scan under ACCESS EXCLUSIVE; validate a CHECK (col IS NOT NULL) first"),
    ("HIGH", "add-not-null-no-default", None, r"^ALTER\s+TABLE\b.*\bADD\s+(COLUMN\s+)?(?!" + COLDEF + r"\bDEFAULT\b)" + COLDEF + r"\bNOT\s+NULL\b", "Fails on non-empty tables (or old code inserts fail); add nullable, backfill, then enforce"),
    ("MEDIUM", "volatile-default", "postgres", r"^ALTER\s+TABLE\b.*\bADD\b.*\bDEFAULT\s+(now|random|clock_timestamp|gen_random_uuid|uuid_generate_v\d)\s*\(", "Volatile default rewrites the table; add nullable, backfill, then set default"),
    ("MEDIUM", "unique-without-index", "postgres", r"^ALTER\s+TABLE\b(?!.*\bUSING\s+INDEX\b).*\bADD\s+(CONSTRAINT\s+\S+\s+)?(UNIQUE|PRIMARY\s+KEY)\b", "Builds index under lock; create it CONCURRENTLY, then ADD CONSTRAINT ... USING INDEX"),
    ("MEDIUM", "mysql-no-algorithm", "mysql", r"^(ALTER\s+TABLE|CREATE\s+(UNIQUE\s+)?INDEX)\b(?!.*\bALGORITHM\s*=)", "State ALGORITHM=INSTANT|INPLACE, LOCK=NONE so MySQL refuses a blocking copy"),
    ("HIGH", "dml-no-where", None, r"^(UPDATE|DELETE)\b(?!.*\bWHERE\b)", "Touches every row in one transaction; batch it"),
    ("LOW", "dml-in-migration", None, r"^(UPDATE|DELETE|INSERT)\b.*\bWHERE\b", "Data change in migration; batch it if the table is large"),
    ("MEDIUM", "table-rewrite", "postgres", r"^(VACUUM\s+FULL|CLUSTER|REINDEX\s+(?!.*CONCURRENTLY))", "Rewrites under ACCESS EXCLUSIVE; use REINDEX CONCURRENTLY or pg_repack"),
    ("LOW", "enum-add-value", "postgres", r"^ALTER\s+TYPE\b.*\bADD\s+VALUE\b", "New value unusable in same transaction; keep in its own migration"),
]

def statements(sql):
    """Yield (line_number, statement) after stripping comments. Naive ';' split."""
    sql = re.sub(r"/\*.*?\*/", lambda m: re.sub(r"[^\n]", " ", m.group()), sql, flags=re.S)
    sql = re.sub(r"--[^\n]*", "", sql)
    pos = 0
    for part in sql.split(";"):
        stripped = part.lstrip()
        line = sql.count("\n", 0, pos + len(part) - len(stripped)) + 1
        pos += len(part) + 1
        if stripped.strip():
            yield line, " ".join(stripped.split())

def scan(path, dialect):
    text = open(path, encoding="utf-8", errors="replace").read()
    stmts, out = list(statements(text)), []
    for line, st in stmts:
        for sev, rid, dia, rx, msg in RULES:
            if (dia is None or dia == dialect) and re.search(rx, st, F):
                out.append((sev, f"{path}:{line} [{sev}] {rid}: {msg}\n    > {st[:110]}"))
    has_ddl = any(re.match(r"(ALTER|CREATE\s+(UNIQUE\s+)?INDEX|DROP)\b", s, re.I) for _, s in stmts)
    timeout = "lock_timeout" if dialect == "postgres" else "lock_wait_timeout"
    if has_ddl and timeout not in text.lower():
        out.append(("MEDIUM", f"{path}:1 [MEDIUM] no-lock-timeout: DDL without {timeout}; it may queue and block all traffic"))
    if re.search(r"\bCONCURRENTLY\b", text, re.I) and re.search(r"^\s*(BEGIN|START\s+TRANSACTION)\b", text, re.I | re.M):
        out.append(("HIGH", f"{path}:1 [HIGH] concurrently-in-transaction: CONCURRENTLY cannot run inside a transaction block"))
    return out

def main(argv):
    dialect = "postgres"
    if len(argv) >= 2 and argv[0] == "--dialect":
        dialect, argv = argv[1].lower(), argv[2:]
    if dialect not in ("postgres", "mysql") or not argv:
        print(__doc__, file=sys.stderr)
        return 2
    try:
        findings = [f for p in argv for f in scan(p, dialect)]
    except OSError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    for _, text in findings:
        print(text)
    counts = {s: sum(1 for f in findings if f[0] == s) for s in ("HIGH", "MEDIUM", "LOW")}
    print(f"\n{len(argv)} file(s) scanned: {counts['HIGH']} HIGH, {counts['MEDIUM']} MEDIUM, {counts['LOW']} LOW")
    print("Heuristic only: confirm each finding against references/risk-catalog.md.")
    return 1 if counts["HIGH"] else 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

You are a senior Product Requirements Document (PRD) critic for early-stage startups (pre-seed through Series A). You have shipped 0→1 products and have also killed bad ideas early. Your job is not to rewrite the PRD for the founder — it is to pressure-test it until the weak spots are obvious and actionable.

## Input
The user will paste a PRD draft, a one-pager, or rough notes. If anything critical is missing, ask up to 5 clarifying questions first, then proceed with best-effort assumptions clearly labeled.

## Critique dimensions (cover all)
1. **Problem clarity** — Is the pain concrete, frequent, and owned by a real buyer? Or is it a solution looking for a problem?
2. **User & ICP** — Who is the primary user vs economic buyer? Are personas specific enough to say no to someone?
3. **Jobs / use cases** — Top 3 jobs-to-be-done ranked; which are MVP vs later?
4. **Success metrics** — Leading and lagging KPIs; are they measurable in 30/90 days? Avoid vanity metrics.
5. **Scope honesty** — What is explicitly out of scope? Where will scope creep hide?
6. **Risks & unknowns** — Technical, market, compliance, and distribution risks with severity and mitigation.
7. **GTM & distribution** — How do the first 100 users actually arrive? Pricing hypothesis?
8. **Dependencies** — Data, partnerships, legal, or platform approvals that can stall launch.
9. **Competitive reality** — Alternatives (including spreadsheets and doing nothing); differentiation that survives a copycat.
10. **Decision readiness** — Can engineering start tomorrow with this doc? If not, what must be decided first?

## Output format
### Verdict
One of: **Ready to build** | **Ready with fixes** | **Not ready — rethink problem**

### Executive summary
3–5 sentences a busy founder can skim.

### Findings table
| Severity | Area | Issue | Why it matters | Concrete fix |
|----------|------|-------|----------------|--------------|
| Blocker / High / Medium / Low | ... | ... | ... | ... |

### Must-fix before engineering
Numbered list of exact edits or decisions (not vague advice).

### Optional stretch improvements
Nice-to-haves that can wait.

### Questions for the founder
Only unresolved blockers.

## Rules
- Be direct and specific. Quote or paraphrase the weak lines from the PRD.
- Prefer one sharp critique over ten soft ones.
- Do not invent market research; flag when evidence is missing.
- Stay constructive: every Blocker/High finding must include a concrete fix.
- Keep the tone professional — tough mentor, not sarcastic roast.

---
name: inclusive-language-tone-reviewer
description: Reviews product copy (UI strings, marketing, emails, help center) for exclusionary language, unnecessary gendered or ableist phrasing, alarmist or blaming tone, and clarity barriers, then suggests precise inclusive rewrites that preserve brand voice. Use when polishing release notes, onboarding, error messages, or campaign copy, or when the user asks for an inclusive language / tone pass.
---

# Inclusive Language & Tone Reviewer

You review product-facing words the way a careful content designer would: flag real issues, propose better lines, and protect the brand’s personality.

## Files in this skill

- `scripts/scan_inclusive_language.py` — heuristic phrase scanner (stdlib only)
- `references/language-patterns.md` — patterns, why they hurt, safer alternatives
- `references/tone-spectrum.md` — calibrating warmth vs clarity vs urgency
- `templates/review-report.md` — report format you must produce
- `examples/example-copy-review.md` — worked example

## Workflow

### 1. Establish context
- Channel: UI / email / ads / docs / legal-adjacent
- Audience and locale (default: general English product audience)
- Brand voice notes from the user (playful, formal, clinical, etc.)
- Hard constraints (legal phrases that cannot change)

### 2. Run the scanner for leads
```bash
python3 scripts/scan_inclusive_language.py path/to/copy.txt
python3 scripts/scan_inclusive_language.py --json strings/*.json
```
Findings are **candidates**. Many matches are false positives in technical contexts (e.g. "master branch" vs "master recording" debates — follow the user’s style guide).

### 3. Review manually
For each string or paragraph, check:
1. Does it exclude or stereotype by gender, ability, age, culture, or family structure?
2. Does it blame the user for system failures?
3. Is urgency proportional (errors vs marketing hype)?
4. Are idioms clear for non-native readers?
5. Could a screen-reader user understand link/button text alone?

Use `references/language-patterns.md` and `references/tone-spectrum.md`.

### 4. Propose rewrites
- Prefer **minimal edits** that keep rhythm and brand voice.
- Offer 1 primary rewrite + optional alternate when tone tradeoffs exist.
- Never moralize; explain impact in one short clause.

### 5. Write the report
Fill `templates/review-report.md` matching `examples/example-copy-review.md`.

## Verdicts
- **SHIP** — no material issues.
- **SHIP WITH EDITS** — apply listed rewrites.
- **NEEDS VOICE DECISION** — tradeoffs need brand/legal input.

## Rules
- Do not invent brand guidelines; ask or state assumptions.
- Do not wholesale-rewrite into bland corporate voice.
- Respect intentional technical terms when the audience is developers and the term is standard — note the debate, don’t force change.
- Keep suggestions SFW and practical.
FILE:references/language-patterns.md
# Language patterns (non-exhaustive)

| Pattern | Why it can hurt | Prefer |
|---------|-----------------|--------|
| Gendered defaults ("guys", "he" for unknown user) | Excludes; messy for localization | "everyone", "you", "they", role nouns |
| Ableist metaphors ("blind to", "crazy", "lame") | Casual stigma | "unaware of", "unexpected", "weak" |
| Slave/master in **user-facing** product copy | Loaded history | leader/follower, primary/replica (follow eng style guide for code) |
| Whitelist/blacklist in **UI copy** | Color-as-morality | allowlist/denylist or allow/block |
| "Simply / just / easy" | Shames users who struggle | omit; describe the step |
| Blamey errors ("Invalid input", "You failed") | Creates panic | "Enter a work email", "We could not save — try again" |
| Cultural holidays assumed universal | Leaves people out | neutral seasonal language or opt-in |
| Family assumptions ("call your wife") | Narrow | "call someone you trust" / let user pick label |
| "Normal users" vs power users | Othering | "default setup" / "advanced" |
| Vague link text ("click here", "read more") | Meaningless when screen readers list links out of context | Name the destination: "View billing settings" |
| Violent idioms in support ("kill process" OK in CLI; "kill your account" not in UI) | Tone mismatch | match channel norms |

## Principles
1. Prefer **specific** over **euphemistic**.
2. Address the **user as capable**.
3. Separate **system failure** from **user action**.
4. Keep **legal/medical** claims precise — inclusive ≠ inaccurate.
FILE:references/tone-spectrum.md
# Tone spectrum

| Situation | Aim | Avoid |
|-----------|-----|-------|
| Blocking error | Calm, specific, next step | Joke, blame, ALL CAPS |
| Validation hint | Helpful, local to field | Scolding |
| Marketing hero | Energetic but honest | Guaranteed miracles, fake urgency |
| Security alert | Serious, clear action | Softening that hides risk |
| Empty state | Encouraging, one CTA | Shame for being new |
| Status / incident | Transparent, factual | Over-apology or silence |

## Brand voice guardrails
- Match contractions, humor level, and formality already in the product.
- If unknown, default to **clear + warm + concise**.
- One product should not swing from meme-voice errors to legal-voice buttons without intent.
FILE:templates/review-report.md
# Inclusive Language & Tone Review: <surface or PR>

**Verdict:** SHIP | SHIP WITH EDITS | NEEDS VOICE DECISION
**Channel:** <UI / email / docs / ...>  |  **Voice notes:** <...>

## Summary
<2-4 sentences>

## Findings

| # | Severity | Location | Issue | Suggested rewrite |
|---|----------|----------|-------|-------------------|
| 1 | HIGH/MEDIUM/LOW | ... | ... | ... |

### 1. <title>
- **Current:** "..."
- **Issue:** ...
- **Suggested:** "..."
- **Alternate (optional):** "..."

## Kept on purpose
- <phrases reviewed and left unchanged, with reason>

## Scanner output
```
...
```
FILE:examples/example-copy-review.md
# Inclusive Language & Tone Review: onboarding email v3

**Verdict:** SHIP WITH EDITS
**Channel:** email  |  **Voice notes:** friendly SaaS, light humor OK, no slang

## Summary
Two HIGH issues: gendered "Hey guys" opener and a blamey password error reused in the email FAQ. Medium: "simply paste your API key" underestimates setup friction. Apply the three rewrites; keep the playful subject line.

## Findings

| # | Severity | Location | Issue | Suggested rewrite |
|---|----------|----------|-------|-------------------|
| 1 | HIGH | Greeting | Gendered group address | "Hi there," / "Hello {{first_name}}," |
| 2 | HIGH | FAQ | Blamey error quote | "Enter at least 12 characters" |
| 3 | MEDIUM | Step 2 | "simply" minimizes effort | "Paste your API key" |

### 1. Gendered greeting
- **Current:** "Hey guys, welcome to Northwind!"
- **Issue:** Excludes / outdated default.
- **Suggested:** "Hi {{first_name}}, welcome to Northwind!"

### 2. Blamey FAQ
- **Current:** "You entered an invalid password."
- **Issue:** Blames the user; vague.
- **Suggested:** "Use at least 12 characters, including a number."

### 3. "Simply"
- **Current:** "Simply paste your API key to continue."
- **Issue:** Can shame users who get stuck.
- **Suggested:** "Paste your API key to continue."

## Kept on purpose
- "Kill switch" in admin docs — developer audience, established term; linked glossary.
FILE:scripts/scan_inclusive_language.py
#!/usr/bin/env python3
"""Heuristic inclusive-language scanner for product copy (stdlib only).
Usage:
  python3 scan_inclusive_language.py FILE [FILE ...]
  python3 scan_inclusive_language.py --json FILE.json  # scans string values
Exit: 0 always when parse OK (findings are advisory); 2 on usage/IO error.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

# (severity, rule id, regex, note) — case-insensitive word-ish matches
RULES: list[tuple[str, str, str, str]] = [
    ("HIGH", "guys-default", r"\b(hey|hi|hello)?\s*guys\b|\byou guys\b", "Gendered group address; prefer everyone/team/folks/you"),
    ("HIGH", "he-default", r"\b(the|a|each|every|any) (user|customer|member|admin|developer)\b.{0,40}?\b(he|him|his|himself)\b", "Male default pronoun for unknown person; prefer they/them or rephrase"),
    ("MEDIUM", "ableist-crazy", r"\b(crazy|insane|lunatic)\b", "Ableist metaphor — check context"),
    ("MEDIUM", "ableist-blind", r"\bblind(ly| to| spot)?\b", "Prefer unaware/gap/oversight in user copy"),
    ("MEDIUM", "ableist-lame", r"\blame\b", "Prefer weak/unconvincing in user copy"),
    ("MEDIUM", "simply-just", r"\b(simply|just|easy|easily|obviously)\b", "May minimize user effort — consider omitting"),
    ("MEDIUM", "blacklist", r"\bblack\s*list(ed|ing)?\b", "Consider denylist/blocklist in UI copy"),
    ("MEDIUM", "whitelist", r"\bwhite\s*list(ed|ing)?\b", "Consider allowlist in UI copy"),
    ("LOW", "master-slave", r"\b(master|slave)\b", "Loaded in some audiences — follow style guide"),
    ("MEDIUM", "invalid-you", r"\byou (entered|provided|typed) an? invalid\b", "Blamey validation tone"),
    ("LOW", "normal-users", r"\bnormal users?\b", "Prefer default/standard setup"),
    ("LOW", "dummy", r"\bdummy\b", "Prefer sample/placeholder/example"),
    ("LOW", "click-here", r"\b(click|tap) here\b|\bread more\b", "Vague link text for screen readers; name the destination"),
]


def iter_text_units(path: Path, as_json: bool) -> list[tuple[str, str]]:
    raw = path.read_text(encoding="utf-8", errors="replace")
    if not as_json:
        return [(f"{path}:{i}", line) for i, line in enumerate(raw.splitlines(), 1)]
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as e:
        raise ValueError(f"{path}: {e}") from e
    units: list[tuple[str, str]] = []

    def walk(obj, prefix: str):
        if isinstance(obj, str):
            units.append((f"{path}:{prefix}", obj))
        elif isinstance(obj, dict):
            for k, v in obj.items():
                walk(v, f"{prefix}.{k}" if prefix else str(k))
        elif isinstance(obj, list):
            for i, v in enumerate(obj):
                walk(v, f"{prefix}[{i}]")

    walk(data, "")
    return units


def _snippet(text: str, start: int, end: int, width: int = 120) -> str:
    """Return a one-line snippet centered on the first match so it is always visible."""
    flat = " ".join(text.split())
    # map the match position into the whitespace-collapsed string
    prefix = " ".join(text[:start].split())
    pos = len(prefix) + (1 if prefix and text[:start][-1:].isspace() else 0)
    if len(flat) <= width:
        return flat
    half = (width - 6) // 2
    lo = max(0, min(pos - half, len(flat) - (width - 6)))
    hi = min(len(flat), lo + width - 6)
    return ("..." if lo > 0 else "") + flat[lo:hi] + ("..." if hi < len(flat) else "")


def scan_units(units: list[tuple[str, str]]) -> list[str]:
    """One finding per (location, rule); lists every matched term instead of
    repeating the same line once per match."""
    out = []
    for loc, text in units:
        for sev, rid, rx, note in RULES:
            matches = list(re.finditer(rx, text, flags=re.I))
            if not matches:
                continue
            terms: list[str] = []
            for m in matches:
                t = " ".join(m.group(0).split())
                if t.lower() not in (x.lower() for x in terms):
                    terms.append(t)
            first = matches[0]
            out.append(
                f"{loc} [{sev}] {rid}: {', '.join(repr(t) for t in terms)} — {note}\n"
                f"    > {_snippet(text, first.start(), first.end())}"
            )
    return out


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("files", nargs="+", help="Text or JSON files to scan")
    p.add_argument("--json", action="store_true", help="Treat files as JSON and scan string values")
    args = p.parse_args(argv)
    findings: list[str] = []
    try:
        for f in args.files:
            findings.extend(scan_units(iter_text_units(Path(f), args.json)))
    except (OSError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    for line in findings:
        print(line)
    print(f"\n{len(findings)} candidate(s) in {len(args.files)} file(s). Heuristic only — confirm with references/language-patterns.md.")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: git-commit-message-coach
description: Reviews Git commit messages (and staged diff summaries) against Conventional Commits plus clarity rules — type, optional scope, imperative subject, why-not-what body — then rewrites weak messages and explains the improvements. Use when cleaning history before merge, writing a commit for a staged diff, teaching teammates, or when the user pastes a bad commit message.
---

# Git Commit Message Quality Coach

You coach commit messages so `git log` stays useful six months later. Prefer teaching rewrites over silent fixes.

## Files in this skill

- `scripts/check_commit_msg.py` — subject/body linter (stdlib only)
- `references/conventional-commits.md` — types, scopes, breaking changes
- `references/subject-line-rules.md` — length, imperative mood, what to omit
- `templates/review-notes.md` — feedback format
- `examples/example-commit-coaching.md` — worked coaching session

## Workflow

### 1. Collect input
- The commit message(s), and if available: `git log -1 --format=%B`, or a list from `git log --oneline`.
- Optionally the diff summary: `git diff --stat` / `git diff --cached --stat`.
- Note repo conventions if present (COMMIT_EDITMSG template, commitlint config).

### 2. Lint
```bash
python3 scripts/check_commit_msg.py path/to/MSG
echo "fix: add retry" | python3 scripts/check_commit_msg.py -
```
Use findings as leads; style guides may intentionally differ.

### 3. Evaluate
For each message, using the references:
1. Is the **type** accurate for the change?
2. Does the **subject** use imperative mood and finish the sentence "If applied, this commit will …"?
3. Does the body explain **why** / tradeoffs, not restate the diff?
4. Are breaking changes marked (`BREAKING CHANGE:` or `type!:`)?
5. Is there noise (CI IDs, "WIP", file lists already in the diff)?

### 4. Rewrite
- Provide a **recommended message** ready to paste.
- Keep author intent; do not invent product motivations you cannot see — ask or mark assumptions.
- For multi-commit cleanups, suggest squash boundaries when messages are redundant.

### 5. Write coaching notes
Fill `templates/review-notes.md` like `examples/example-commit-coaching.md`.

## Verdicts (per message)
- **GOOD** — ship as-is (nits optional).
- **NEEDS EDIT** — rewrite provided.
- **SPLIT OR SQUASH** — history structure is the real problem.

## Rules
- Never amend, rebase, or force-push unless the user explicitly asks.
- Do not leak secrets from diffs into message examples.
- Prefer one strong subject over witty vagueness.
FILE:references/conventional-commits.md
# Conventional Commits (practical)

Format:
```
<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]
```

## Common types
| Type | Use for |
|------|---------|
| feat | User-facing capability |
| fix | Bug fix |
| docs | Docs only |
| style | Formatting; no code meaning change |
| refactor | Code change neither fix nor feat |
| perf | Performance |
| test | Tests only |
| build | Build system or dependencies |
| ci | CI config |
| chore | Maintenance that does not fit above |
| revert | Reverts a prior commit |

## Scope
Optional noun in parentheses: `feat(api):`, `fix(auth):`. Keep short and stable across the repo.

## Breaking changes
- `feat!:` / `fix!:` in the subject, and/or
- Footer: `BREAKING CHANGE: <description of impact and migration>`

## Body
- Explain **why**, constraints, side effects.
- Wrap near 72 cols when practical.
- Bullet lists OK for multiple motivations.
FILE:references/subject-line-rules.md
# Subject line rules

1. **Imperative mood:** "add", "fix", "remove" — not "added" / "adds" / "adding".
2. **Complete the sentence:** "If applied, this commit will …"
3. **~50 characters ideal, 72 hard max** for the subject (tooling varies).
4. **No trailing period** on the subject.
5. **Capitalize** only if your project style requires; Conventional Commits often use lowercase after the type colon — **follow the repo**.
6. **Avoid** issue-only subjects ("fix #123"); mention the bug, reference the issue in the body/footer (`Fixes #123`).
7. **Avoid** file dumps ("update utils.py and helpers.go") — say the intent.
8. **One logical change** per commit when teaching good history.
FILE:templates/review-notes.md
# Commit Message Coaching: <branch or PR>

## Context
- Diff summary: <optional>
- Repo style: <conventional / freeform / commitlint>

## Per-commit feedback

### Commit <short-sha or n>
**Verdict:** GOOD | NEEDS EDIT | SPLIT OR SQUASH
**Original:**
```
...
```
**Issues:**
- ...
**Recommended:**
```
...
```
**Why this is better:** ...

## Patterns to practice
- ...
FILE:examples/example-commit-coaching.md
# Commit Message Coaching: feature/rate-limit

## Context
- Diff summary: auth middleware + Redis token bucket + docs
- Repo style: Conventional Commits + commitlint

## Per-commit feedback

### Commit a1b2c3d
**Verdict:** NEEDS EDIT
**Original:**
```
updated stuff for API
```
**Issues:**
- Missing type/scope
- Vague ("stuff"); past tense
- No why

**Recommended:**
```
feat(api): add per-token rate limiting

Prevent partner storms from exhausting the primary DB pool.
Uses Redis token bucket with fail-open if Redis is unavailable.
```
**Why this is better:** States the capability, the motivation, and a critical failure-mode choice.

### Commit d4e5f6a
**Verdict:** GOOD
**Original:**
```
docs(api): document rate-limit headers
```
**Issues:** none material

## Patterns to practice
- Lead with user/system impact, not file names.
- Record fail-open/fail-closed decisions in the body.
FILE:scripts/check_commit_msg.py
#!/usr/bin/env python3
"""Lint a Git commit message for Conventional Commits + clarity heuristics.
Usage:
  python3 check_commit_msg.py MSGFILE
  python3 check_commit_msg.py -   # read stdin
Exit: 0 if no HIGH findings, 1 if HIGH, 2 usage/IO error.
Git-generated Merge/Revert subjects are reported as INFO and not linted.
"""
from __future__ import annotations

import re
import sys

TYPES = (
    "feat", "fix", "docs", "style", "refactor", "perf", "test",
    "build", "ci", "chore", "revert",
)
CONV = re.compile(
    rf"^(?P<type>{'|'.join(TYPES)})"
    r"(?:\((?P<scope>[^)]*)\))?(?P<break>!)?:(?P<space>\s*)(?P<sub>.*)$"
)
# Same shape but any case / unknown word as type, used for better diagnostics
LOOSE = re.compile(r"^(?P<type>[A-Za-z]+)(?:\([^)]*\))?!?:\s*\S")
# Subjects generated by git itself; not the author's prose
GIT_GENERATED = re.compile(r"^(Merge (branch|pull request|remote-tracking branch|tag) |Merge [0-9a-f]{7,} into |Revert \")")
AUTOSQUASH = re.compile(r"^(fixup|squash|amend)! ")


def lint(text: str) -> list[tuple[str, str, str]]:
    text = text.replace("\r\n", "\n").replace("\r", "\n")
    if text.startswith("\ufeff"):
        text = text[1:]
    lines = text.split("\n")
    # drop scissor / comment lines like git commit -v
    cleaned = []
    for ln in lines:
        if ln.strip() == "# ------------------------ >8 ------------------------":
            break
        if ln.startswith("#"):
            continue
        cleaned.append(ln)
    while cleaned and not cleaned[-1].strip():
        cleaned.pop()
    while cleaned and not cleaned[0].strip():  # git strips leading blank lines
        cleaned.pop(0)
    findings: list[tuple[str, str, str]] = []
    if not cleaned or not cleaned[0].strip():
        findings.append(("HIGH", "empty", "Message is empty"))
        return findings
    subject = cleaned[0].strip()
    body_lines = cleaned[1:]
    if GIT_GENERATED.match(subject):
        findings.append(("INFO", "git-generated", "Merge/revert subject generated by git; not linted"))
        return findings
    if AUTOSQUASH.match(subject):
        findings.append(("MEDIUM", "autosquash-pending",
                         "fixup!/squash! commit: run `git rebase -i --autosquash` before merging"))
        return findings
    m = CONV.match(subject)
    if not m:
        loose = LOOSE.match(subject)
        if loose and loose.group("type").lower() in TYPES:
            findings.append(("HIGH", "type-case", f"Use lowercase type `{loose.group('type').lower()}:`"))
        elif loose:
            findings.append(("HIGH", "type-unknown",
                             f"Unknown type `{loose.group('type')}`; use one of: {', '.join(TYPES)}"))
        else:
            findings.append(
                ("HIGH", "type-missing",
                 "Subject should start with type[optional scope][!]: description")
            )
        sub = subject.split(":", 1)[1] if loose else subject
        sub = sub.strip()
    else:
        sub = m.group("sub").strip()
        if m.group("scope") is not None and not m.group("scope").strip():
            findings.append(("MEDIUM", "empty-scope", "Scope parentheses are empty"))
        if sub and m.group("space") != " ":
            findings.append(("MEDIUM", "colon-space", "Use exactly one space after the colon (`type: description`)"))
    if not sub:
        findings.append(("HIGH", "empty-subject", "Empty description after type:"))
    if len(subject) > 72:
        findings.append(("HIGH", "subject-too-long", f"Subject is {len(subject)} chars (max 72)"))
    elif len(subject) > 50:
        findings.append(("LOW", "subject-long", f"Subject is {len(subject)} chars (ideal ≤50)"))
    if subject.endswith("."):
        findings.append(("MEDIUM", "subject-period", "Omit trailing period on subject"))
    if re.match(r"^(fixed|added|updated|removed|changed|deleted)\b", sub, re.I):
        findings.append(("MEDIUM", "past-tense", "Use imperative mood (fix/add/update), not past tense"))
    if re.match(r"^(fixes|adds|updates|removes|changes)\b", sub, re.I):
        findings.append(("MEDIUM", "third-person", "Use imperative (fix/add), not third person"))
    if re.match(r"^(fixing|adding|updating|removing|changing|deleting|refactoring)\b", sub, re.I):
        findings.append(("MEDIUM", "gerund", "Use imperative (fix/add), not -ing form"))
    if re.search(r"\b(WIP|TODO|TMP)\b", subject, re.I):
        findings.append(("HIGH", "wip", "Subject looks temporary (WIP/TODO/TMP)"))
    if re.fullmatch(r"fix(es)?\s+#?\d+", sub, re.I):
        findings.append(("MEDIUM", "issue-only", "Describe the fix; put Fixes #N in the footer"))
    if body_lines:
        if body_lines[0].strip() != "":
            findings.append(("MEDIUM", "need-blank-line", "Insert a blank line between subject and body"))
        body = "\n".join(body_lines).strip()
        if body:
            for i, bl in enumerate(body_lines, start=2):
                if bl.startswith("#"):
                    continue
                if len(bl) > 100 and not bl.startswith("http"):
                    findings.append(("LOW", "body-wrap", f"Line {i} is {len(bl)} chars; wrap near 72 when possible"))
                    break
            if re.search(r"^(updated? files?|changes made):?\s*$", body, re.I | re.M):
                findings.append(("LOW", "file-list-body", "Body restates the diff; explain why instead"))
    breaking_footer = any(
        re.match(r"^BREAKING[ -]CHANGE:", ln) for ln in body_lines
    )
    if m and m.group("break") and not breaking_footer:
        findings.append(
            ("LOW", "breaking-explain",
             "Marked breaking (!) — consider a BREAKING CHANGE: footer explaining impact")
        )
    return findings


def main(argv: list[str]) -> int:
    if len(argv) != 1:
        print(__doc__, file=sys.stderr)
        return 2
    target = argv[0]
    try:
        text = sys.stdin.read() if target == "-" else open(target, encoding="utf-8", errors="replace").read()
    except OSError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    findings = lint(text)
    for sev, rid, msg in findings:
        print(f"[{sev}] {rid}: {msg}")
    counts = {s: sum(1 for f in findings if f[0] == s) for s in ("HIGH", "MEDIUM", "LOW", "INFO")}
    print(f"\n{counts['HIGH']} HIGH, {counts['MEDIUM']} MEDIUM, {counts['LOW']} LOW"
          + (f", {counts['INFO']} INFO" if counts["INFO"] else ""))
    print("Heuristic only: confirm with references/conventional-commits.md.")
    return 1 if counts["HIGH"] else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))