---
name: project-health
description: Use when checking, creating, reviewing, or updating PRD Plugin project health findings, `.prd_plugin/state/health.json`, `HLT-*` records, stale tracking items, orphan requirements, missing evidence, weak traceability, or readiness to continue implementation/planning work.
---

# Project Health

## Deterministic Maintenance

Plan and run `project.maintenance` when enabled. It owns config audit, state
consistency, staleness audit, and graph construction. Use `prd_find`/`prd_get`
to inspect exact findings, `prd_create`/`prd_update` for HLT lifecycle, and
`prd_link` for relationships; never calculate a record-backed ID manually.

The drift monitor also surfaces `ingest_manual_drift` for cited ingest-manual
sources and `fork_version_check` when `fork.version_check` is configured. Both
are fail-open/no-op when not applicable; report their effective configuration
instead of assuming they ran.

Use this skill to produce a compact operational health check for a project using
the PRD Plugin method.

## Rules

- Store health snapshots in `.prd_plugin/state/health.json`.
- Read `.prd_plugin/config.json` when present; `paths.health_file` and
  `health.*` settings may override default health behavior.
- Use `HLT-###` IDs for health findings.
- Health findings are operational warnings, not project truth.
- Cite affected IDs or source files for every finding.
- Include `checked_by_agent` as `AGENT-*` and `checked_from_session` as `SES-*`
  when known.
- Prefer updating existing open `HLT-*` findings over duplicating them.
- Close findings only when the linked source, evidence, or state record shows
  the issue is resolved.
- Triage every new finding to one of four owners instead of leaving it open
  indefinitely: **escalate** (needs authority/decision → `project-blocker-resolution`
  or a `REQ-*`), **implement** (actionable now → graduate to `TRK-*`/`IMP-TASK-*`),
  **warn** (track-only, acceptable residual risk → keep open with a re-check
  date), or **close** (resolved or not-a-finding, with the resolving evidence).
  Record the chosen disposition on the `HLT-*`.

## Check Areas

Review:

1. PRD requirements: orphan `PRD-*` items, missing sources, weak acceptance criteria.
2. Architecture: unmapped `ARCH-*` components, decisions, interfaces, or risks.
3. Implementation plans: `IMP-TASK-*` items without PRD, architecture,
   validation, or evidence expectations.
4. Evidence: completion claims without `EV-*`, weak evidence, missing limitations.
5. Document branches: promoted `DBR-*` branches without evidence, anchors,
   merge decisions, or regression conditions.
6. Agent memory: promoted `MEM-*`, `TRK-*`, or `CHG-*` records without
   source references, `AGENT-*`, or `SES-*` provenance.
7. Tracking: stale, blocked, duplicated, or already-resolved `TRK-*` records.
8. Changelog: missing `CHG-*` records for material PRD, architecture, plan,
   state, or promotion changes.
9. Requests/issues: stale, unclear, duplicate, accepted `REQ-*` records that
   have not graduated into tracked work or documented decisions, persistent bug
   repros recorded as new `REQ-*` records instead of `MSG-*` thread updates,
   `in_review` or `needs_info` requests with no recent `MSG-*` reply,
   implemented requests that lack `graduated_to` links, or high-severity
   bugs/compatibility issues without reproduction details or tracking links.
10. Release hygiene: version-impacting changes without required release state,
    or skill/method changes without companion docs/templates when required by
    config.
11. Version advice: release metadata missing for published versions, stale
    installed-version markers, or `version_change` requests without current and
    requested versions.
12. Pre-bump checks: version bumps performed before configured pre-bump findings
    were resolved or recorded as explicit follow-up.
13. Cross-artifact hygiene: changes that updated one artifact but missed related
    docs, skills, templates, config, state, tests, or workflows.
14. Privacy: local repos exposing other repos' requests/messages, indexing
    `.prd_plugin/local/`, submitting unsanitized local state upstream, or
    marking private `MSG-*` replies for upstream visibility.
15. Request transport: inbox packages graduated without review, downstream
    repos pulling another repo's mailbox, or stale outbox packages that were
    never imported by the hub.
16. Automation guard: stale `.prd_plugin/local/automation/*.lock.json` files,
    unconsumed pending markers, or scheduled request checks that run without
    the single-run guard.
17. Scheduler state: request/mailbox automation answers based only on local
    locks instead of also checking `%USERPROFILE%/.codex/automations/<automation-id>/automation.toml`
    for recurrence and pause state.
18. State consistency: evidence or session summaries claiming missing
    `MEM-*`, `TRK-*`, `CHG-*`, `OBS-*`, or `SES-*` records, registry counters
    that skip absent canonical records, or future timestamps in state/fixtures.

Run the required downstream validator
`python scripts/state_consistency_check.py --repo-root .` before marking health
`healthy` for repos with PRD Plugin state.

## Version Check Procedure

`version_advice.py` is a hub-only script; do not run it from a downstream repo's
installed scripts. When checking item 11 (Version advice), if the repo uses PRD
Plugin and the installed version may be stale, run `version_advice.py` only from
a local copy of the PRD Plugin hub/development repo:

```bash
python scripts/version_advice.py \
  --installed-repo <path-to-this-repo> \
  --write-request \
  --requests <path-to-this-repo>/.prd_plugin/state/requests.json
```

The script reads the installed version from `.prd_plugin/config.json`,
`.codex-plugin/plugin.json`, `.opencode/plugin.json`, or
`.prd_plugin/state/project.json`, compares it with the hub's
`.prd_plugin/state/releases.json`, and appends a `version_change` request when
the recommendation is `review_first` or `blocked`. Include the recommendation,
newer releases, and any migration blockers in the health finding.

## Staleness Coverage

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


Use `requests.stale_after_days`, `health.stale_tracking_after_days`,
`health.accepted_request_stale_after_days`, and
`automation.stale_after_seconds` from config when present. Staleness findings
should include the stale record ID, last activity timestamp when known, threshold
used, and whether the item should be resolved, refreshed, superseded, or carried
forward.

## Health Status

Use one of:

- `healthy`: no material findings.
- `attention_needed`: findings exist but work can continue carefully.
- `blocked`: findings prevent reliable continuation.
- `not_checked`: no health check has been performed.

## Finding Shape

Each finding should include:

1. `id`
2. `severity`: `low`, `medium`, `high`, or `critical`
3. `status`: `open`, `resolved`, `accepted`, or `superseded`
4. `summary`
5. `affected_ids`
6. `source_refs`
7. `recommended_action`
8. `created_at`
9. `resolved_at`, when resolved

## Output Shape

Lead with findings ordered by severity. Include the resulting health status,
updated `HLT-*` IDs, and any residual risk.