---
name: project-self-audit
description: Use when a downstream repo wants to measure the gap between the rules it has stated in AGENTS.md or CLAUDE.md and what its source code actually shows. Mines lightweight signals (rule phrases, debt markers, session transcripts, consistency-check output), produces a rule-vs-reality gap report, and optionally writes a REQ-* request and a HLT-* health finding for the most-violated rules.
---

# Project Self Audit

This skill turns PRD Plugin into a self-aware meta-tool. It walks a
single repo, compares the anti-pattern rules the maintainer has
stated (in `AGENTS.md` or `CLAUDE.md`) against the debt markers that
actually exist in the source code, and reports the gap. When the gap
is significant it writes a `REQ-*` and a `HLT-*` to the repo's
`.prd_plugin/state/`.

The skill is a lightweight, repository-local audit. It uses only shipped PRD
Plugin code and the current repository; it has no dependency on another local
checkout or external analysis corpus.

## When To Use

- The operator wants to know whether the rules they wrote in
  `AGENTS.md` / `CLAUDE.md` are actually being followed.
- A repo has accumulated debt markers (`TODO`, `FIXME`, `MOCK`,
  `STUB`, `HACK`, `WORKAROUND`, `XXX`, `PLACEHOLDER`) and the
  operator wants a structured gap report before deciding what to
  enforce.
- An agent detects rule drift in a session and wants a
  point-in-time rule-vs-reality snapshot.
- The repo wants to bootstrap a `REQ-*` queue with the top
  enforcement candidates without manually grepping for markers.

## When NOT To Use

- The repo has no `AGENTS.md` and no `CLAUDE.md`. The audit will
  report an empty rule list and a debt-marker summary; that is
  valid but not actionable.
- The operator wants tool-call-level session analysis. That is outside this
  bounded rule/debt-marker audit; use a separately configured observability
  system rather than assuming one exists.
- The operator wants to act on a specific rule. Open a `REQ-*`
  directly with `project-request-intake` instead of running
  the audit.

## Usage

```bash
# Read-only gap report (default markdown).
python .prd_plugin/scripts/prd_self_audit.py --repo-root . --format markdown

# Persist REQ-* and HLT-* records for high-leverage rules
# (>=3 violations per rule phrase).
python .prd_plugin/scripts/prd_self_audit.py --repo-root . --format markdown --persist

# JSON output for tooling.
python .prd_plugin/scripts/prd_self_audit.py --repo-root . --format json
```

In the hub development repo only, resolve the same helper at
`scripts/prd_self_audit.py`.

The script reads `.prd_plugin/config.json` only to know that the
state directory exists. It does not require any other
configuration.

## Output Shape

The markdown report has three sections:

1. **Summary** — rule count, marker count, violated-rule count,
   high-leverage rule list.
2. **Rule Violations** — one row per rule phrase with its
   violation count.
3. **Debt Markers** — one row per marker with its count.

The JSON report contains the same data in a structured form:

```json
{
  "repo": "...",
  "checked_at": "YYYY-MM-DD",
  "rules": [{"phrase": "no todos", "source": "agents_or_claude", "violations": 7}],
  "markers": [{"marker": "TODO", "count": 7}],
  "summary": {"rule_count": 2, "marker_count": 7, "violated_rule_count": 1, "high_leverage": ["no todos"]}
}
```

## Persisted Findings

When the audit runs with `--persist` and a rule has
`violations >= 3`, the script writes:

- A `REQ-*` request of type `method` to
  `.prd_plugin/state/requests.json` with the violation count,
  affected areas, and reproduction steps.
- A `HLT-*` health finding of severity `medium` to
  `.prd_plugin/state/health.json` citing the same rule phrase
  and the linked request ID.

The threshold is intentionally low (3 violations) so a real
"no TODOs in this repo" rule with even a few slip-throughs
becomes a trackable item.

## Hard Rules

- **Never modify code.** The audit is read-only except for
  writing `REQ-*` / `HLT-*` records to the repo's own
  `.prd_plugin/state/`.
- **Never write a `REQ-*` for trivial gaps.** Violations below
  the `SIGNIFICANT_VIOLATION_THRESHOLD` (3) are reported but not
  persisted.
- **Never invent rules that are not in `AGENTS.md` /
  `CLAUDE.md`.** The audit only counts violations for rules
  the maintainer has actually stated.
- **Never treat the audit as a license to delete rules.** A
  rule that is heavily violated is a candidate for enforcement,
  not removal. Discuss with the operator before changing the
  rule files.
- **Never run the audit and persist in a loop.** A single pass
  is enough; the persisted records will be tracked through
  `project-request-intake` and `project-traceability-sync`
  like any other `REQ-*` / `HLT-*`.

## Companion Skills

- `project-request-intake` — for the persisted `REQ-*` records.
- `project-health` — for the persisted `HLT-*` records.
- `project-traceability-sync` — for linking the gap-finding
  `REQ-*` to a longer-term `DEC-*` or `IMP-TASK-*` if the
  operator decides to act on it.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


The audit reads the source code as it is at run time. Re-run
the audit after any of:

- a rule was added or removed in `AGENTS.md` / `CLAUDE.md`
- a large refactor changed the debt-marker density
- the operator resolved one of the persisted `REQ-*` records