skills.rest
PeteRichardson
PeteRichardsonCOMMUNITY
Explore all skills by this author →
GitHub

project-review

Audits an entire codebase for tech debt and writes a cited findings report to docs/reviews/PROJECT_REVIEW.md.

Updated Jun 4, 2026
Search Tags:#code quality#static analysis#code review#code audit#tech debt#architecture review#git history
One-click install
npx skills add https://github.com/PeteRichardson/skills --skill project-review-peterichardson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: project-review
Source: https://github.com/PeteRichardson/skills/tree/main/project-review
Command: npx skills add https://github.com/PeteRichardson/skills --skill project-review-peterichardson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Inheriting or resurrecting a repository leaves you without a map of where the technical debt actually concentrates. This Skill performs a structured, whole-repo architecture and tech-debt audit, producing a ranked findings report with file:line citations instead of vague best-practice advice. ## Core Features & Use Cases - Phased audit protocol: Orients via README, manifests, and git churn history, then audits across 13 dimensions including architectural decay, test debt, security hygiene, idiom debt, and data integrity. - Cited, ranked findings report: Writes docs/reviews/PROJECT_REVIEW.md with severity and effort estimates, quick wins, top-5 fixes, and a required "looks bad but is actually fine" section. - Stable finding IDs and repeat runs: Derives finding IDs from git history so regenerated reports never collide with IDs cited in commit messages, and marks resolved/new findings on subsequent runs. - Use Case: You just inherited an unfamiliar repo and ask "what should I work on next?" The Skill scans churn hotspots, runs stack-specific linters and audit tools, and delivers a prioritized debt report you can feed into issue creation. ## Quick Start Run /project-review in the repository you want audited and it will write the full findings report to docs/reviews/PROJECT_REVIEW.md.

Frequently Asked Questions about project-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a codebase for technical debt?▼

Run /project-review in the repository root. It reads the README and manifests, analyzes git churn to find debt hotspots, audits 13 dimensions from architectural decay to security hygiene, and writes a ranked findings report with file:line citations to docs/reviews/PROJECT_REVIEW.md.

What is the difference between /project-review and /code-review?▼

/project-review is whole-repo and architectural, finding where debt concentrates across modules. /code-review is tactical and line-level, used on specific files or folders that the audit flags. Run /project-review first on an unfamiliar repo, then /code-review on flagged areas.

Which languages and tools does the audit support?▼

It detects the stack from the package manifest and runs relevant tools: npm audit, knip, and madge for TypeScript/JavaScript; pip-audit, ruff, and vulture for Python; cargo audit and clippy for Rust; govulncheck and staticcheck for Go; swiftlint and periphery for Swift; clang-tidy and cppcheck for C/C++.

Does the audit work on large repositories?▼

For repos over 50k LOC or with more than 5 top-level modules, it can dispatch parallel subagents per module and merge their findings. For very large repos over 200k LOC, scoping to a single module is recommended to avoid shallow results.

What happens when I run the audit a second time?▼

Repeat-run mode reads the existing PROJECT_REVIEW.md, marks resolved findings as RESOLVED, updates stale ones, and tags new findings with NEW. Finding IDs are derived from a git-history scan so regenerated reports never reuse IDs already cited in commit messages.

What are the limitations of a static codebase audit?▼

It is a static audit, not a security audit or business-logic reviewer, and cannot distinguish intentional simplicity from accidental simplicity. Ambiguous cases are listed in the open-questions section for the maintainer rather than asserted as findings.

Related Skills

Explore More Software Engineering Skills→
xiaoquqixiaoquqi

code-insights-redesign

Automate code-review workflows with full-clone history and structured summaries.

Community
Advanced
warpdotdevwarpdotdev
292

dedupe-issue

Compare GitHub issue titles and descriptions to flag potential duplicates.

Official
Intermediate
kaminocorpkaminocorp
1

codebase-inspection

Inspect repositories with pygount to count lines of code and analyze language composition.

Official
Basic
EngineerWithAIEngineerWithAI
4

sast-configuration

Configure Semgrep, SonarQube, and CodeQL for automated vulnerability detection.

Official
Intermediate