Run the project's quality/health tools (from CLAUDE.md Commands section):
# Use project-specific commands, e.g.:# just health, npm run lint, cargo clippy, etc.
Report on:
Complexity trends (should be stable or decreasing)
Duplication percentage (target: <5%)
High-churn files that may need attention
Dead code: unused exports, orphaned functions (run monthly or when codebase > 5K LOC)
2. Code Quality Agent Review
Use the code-quality skill to analyze the entire codebase:
Flag any functions with CCN >10
Identify duplication patterns
Check for pattern consistency violations
3. Documentation Review
Check key documentation for accuracy:
@CLAUDE.md accuracy (commands, paths, patterns still correct?)
@docs/progress.md completeness
Any drift between docs and implementation
Documentation efficiency: Key context files (CLAUDE.md, progress.md, BACKLOG_INDEX.md) are loaded every session — keep them lean. Archive stale content, deduplicate, condense verbose sections.
Metrics freshness: If docs/progress.md → ## Sprint History has ≥2 data rows but ## Metrics table still shows "—" values, sprint-end is not computing metrics — flag as a measurement gap. The feedback loop is broken: data collected but not surfaced.
4. Dependency Review
Check for outdated dependencies using the project's package manager:
# npm outdated, pip list --outdated, cargo outdated, etc.
Read `docs/reference/SECRETS_INVENTORY.md` and check:
- **Overdue rotations:** Scan the `Next Due` column for dates in the past. Flag by severity: ≤7 days (warning), 8-30 days (high priority), >30 days (critical — rotate immediately).
- **Missing rotation methods:** Any secrets without a documented `Rotation Method` should be flagged.
- **Critical secrets without automation:** Secrets classified as `critical` that rely on `manual` rotation are high-risk.
If `docs/reference/SECRETS_INVENTORY.md` does not exist but the project uses environment variables or credentials, note this as a gap: "No secrets inventory — consider creating one from the template in the framework scaffold."
Check the health of project ground rules:
Review the health of architecture decision records:
Recently deprecated packages — check for deprecation notices
Dependency Report
### Dependency Health- Total dependencies: [count]
- Outdated: [count]
- Vulnerabilities: [critical/high/medium/low counts]
- Recently added: [list with age and download counts]
- Lockfile in sync: [yes/no]
4.3. Security Health Check
Perform a focused security health review:
Secrets Inventory Review
Dependency Security Audit
Run the project's dependency audit tool (same as section 4, but focused on security):
Report any findings. This catches secrets missed by the per-file post-edit hook.
4.5. Technical Debt Register Review
Read docs/technical-debt.md and perform the weekly debt review:
Triage active items
For each active item:
Interest rate reassessment — check coupling to determine if interest is Growing or Stable. Run grep -rn on the debt item's Location files to count how many other files import/reference them. High fan-in (imported by >5 files) + active debt = Growing interest. Isolated files with no dependents = Stable or Shrinking.
Severity check — has the item worsened? (e.g., new incidents, more files affected). Promote if so.
Resolution progress — is there a linked story? If not and item is >30 days old, consider creating one.
Accept or resolve — can any items move to "Accepted" (conscious trade-off) or "Resolved" (fixed)?
Detect new debt
Check this week's commits and code quality findings for new debt. Specifically scan for the 5 AI-specific debt types:
Comprehension debt — grep git log for AI-assisted commits (Co-Authored-By: Claude or similar). For files with high AI-commit ratio that haven't been manually modified since, flag as potential comprehension debt. The risk: code ships faster than developers understand it.
Pattern violation debt — compare this week's changes against docs/reference/CODING_STANDARDS.md (if exists). AI introduces inconsistent patterns at 3x the human rate for formatting, 2x for naming.
Duplication debt — check for near-duplicate code blocks introduced this week. AI regenerates rather than reusing existing functions.
Phantom dependency debt — verify all imports added this week reference packages that exist in the project's dependency manifest (package.json, requirements.txt, go.mod, Cargo.toml, etc.).
Verification debt — check if large AI-generated diffs have corresponding test coverage. Code reviewed without full understanding creates hidden risk.
Tag new items with origin: ai-generated when the source commit has AI co-author markers.
Housekeeping
Review dates — update "Last reviewed" to today, "Next review" to +7 days
Resolved cleanup — delete resolved items older than 90 days
AI trends — at quarter boundaries, update the AI Debt Trends table with counts
Active count — update header: Active items: X | Resolved this quarter: Y
Sprint candidates — flag items with priority score ≥4.5 or interest "Growing" for next sprint planning. /sprint-start reads these during its debt health check.
5. Rule Health Review
Run the metrics script to assess rule effectiveness:
bash scripts/pm/metrics.sh
Review the "Rule Triggers" section. Flag:
Over-active rules (>20 triggers/week) — may be too broad or indicating a persistent issue
Silent rules (0 triggers in 30+ days) — may be too narrow or addressing a solved problem
High-failure skills (success rate <70%) — investigate common failure points
Record findings in the weekly summary below.
Also run the progress dashboard for trend signals and relative changes:
bash scripts/pm/metrics.sh --progress
Review the output for:
Any metrics with Δ3avg >50% (rapid change worth investigating)
Leading vs Lagging divergences (early warning signals)
Persistent 3-sprint trends that haven't been addressed
5.5. Ground Rules Health
Expired exceptions — scan the Exception Log table for rows where Expires date has passed. Flag for resolution (remove exception or renew with justification).
Stale rules — if Change History shows no updates in 6+ months, the rules may need a freshness review.
Compliance trends — read recent sprint specs (docs/sprints/sprint-N.md) → ## Outcome → Ground rules field. Consistent violations of one rule may mean the rule is unrealistic, or enforcement is missing.
Enforcement gaps — for rules with Enforced-by: auto:, verify the tool/test still exists and runs in CI. Unconfigured enforcement = paper rule.
5.7. Architecture Decision Health
Low-confidence ADRs — scan for confidence: low in frontmatter. For each, check whether Reconsider when conditions have been met by the current codebase state. Flag any that need re-evaluation.
Stale ADRs — if no ADR has been created or reviewed in 90+ days on an actively developed project, the team may be making undocumented decisions. Flag as a process gap.
Supersession chains — check for superseded-by chains longer than 2 (A→B→C). These indicate a volatile decision area that may need a ground rule instead.
Ground rule candidates — if 2+ accepted ADRs address the same concern, suggest promoting to docs/reference/GROUND_RULES.md.
ADR count health — projects with <5 ADRs and >10 major dependencies are likely under-documenting decisions.
5.9. Weekly Activity Insights
Parse docs/sessions/.activity-log.jsonl for the past 7 days of activity:
ACTIVITY_LOG="docs/sessions/.activity-log.jsonl"
WEEK_AGO=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d "7 days ago" +%Y-%m-%d 2>/dev/null)
if [ -f "$ACTIVITY_LOG" ] && [ -s "$ACTIVITY_LOG" ]; then# Filter to last 7 days and analyze# Top 3 most-edited files this week# Skill invocation counts# Test failure patterns (same test failing repeatedly = flaky or fundamental)# Edit-to-test ratio for the weekfi
