Repo Reviewer — Repository Analysis from a PdM Perspective

1. List root directory files
2. Map the directory structure 2–3 levels deep
3. Prioritize reading these files:
   • README.md / README
   • Language-specific manifests (package.json / Cargo.toml / go.mod / composer.json, etc.)
   • Makefile / Dockerfile / docker-compose.yml
   • CI configs under .github/workflows/
   • CHANGELOG.md / HISTORY.md
   • CONTRIBUTING.md

Step 2: Identify the Tech Stack

From manifests and code, identify:

• Programming language(s) and version(s)
• Frameworks and libraries (distinguish core vs. utility)
• Test framework
• Build tools / task runners
• CI/CD pipeline
• Infrastructure / deployment setup

Step 3: Read the Architecture

Infer architectural patterns from directory layout and code dependencies:

• Layered? Clean architecture? Monolith? Microservices?
• Where is the entry point?
• Data flow (input → processing → output)
• Integration points with external services

Step 4: Operational Assessment (the core of this skill)

4a. Documentation Completeness

• Does the README cover setup, running, and testing?
• For features with evolving specs, are the rationale and change history recorded?
• Is there a clear pointer to where the latest information lives (URLs, search keywords)?
• Do API or config docs match the actual code?

4b. Maintainability

• Do code comments explain "why" (not just "what")?
• Are there magic numbers or implicit assumptions left undocumented?
• Is error handling adequate? (Silent failures are an operational hazard.)
• Is log output production-ready?

4c. Testing and Quality Assurance

• Approximate test coverage (presence and breadth of test files)
• What does CI check?
• Is there a pre-release checklist?

4d. Compatibility and Migration

Versioning and CHANGELOG are assumed to be automated. Focus here on what requires human effort.

• If there are breaking changes, is a migration guide provided? (This is mandatory. Breaking changes without a migration guide do not pass review.)
• Does the migration guide include:
  • A list of affected APIs, configs, and data structures
  • Concrete before → after rewrite examples
  • Step-by-step migration procedure (including intermediate states when bulk migration isn't feasible)
  • Instructions for running automated migration scripts, if any
• For deprecations, are the target removal version and migration destination documented?

Review Output Format

Report analysis results in this structure:

## Repository Overview
Name, purpose, tech stack summary

## Architecture
Structure overview, data flow, key components

## Operational Assessment

### Documentation
Current state and missing items

### Maintainability
Code quality, comment quality, error handling

### Testing & CI
Test coverage, CI configuration assessment

### Compatibility & Migration
Migration guide availability and quality, deprecation handling

## Recommended Actions
Prioritized list of specific improvement proposals.
Each item includes "why it matters (from an operational cost perspective)."

## Reference Links
- URLs to follow for the latest information about this repository
- Links to relevant official documentation
- Useful search keywords for troubleshooting

Documentation Generation Rules

When generating or updating READMEs and documentation, always include:

1. Setup instructions: The shortest path from environment setup to a running state
2. Development workflow: Branch strategy, commit message conventions, PR rules
3. Test execution: Commands to run tests locally and expected results
4. Deployment procedure: How to ship to production
5. Troubleshooting: Common issues and solutions
6. Reference information:
   • URLs to related external documentation
   • Where to find the latest version of the spec
   • Search keywords that help locate answers (e.g., "search '○○ error fix' to find solutions")
7. Update responsibility: When and who should update this document

For features with evolving specs, explicitly state:

• What stage the current spec is at (finalized / provisional / under discussion)
• The history and rationale behind spec changes
• How to check the latest spec (URL, point of contact, Slack channel, etc.)

Code Review Perspective

When reviewing PRs or code changes, focus on:

Scope Limitation

When working on a topic branch, reviews and feedback should be limited to the scope of changes in that branch. However, if a change relates to something outside the scope and the resulting documentation update would be beneficial from an external perspective, updating out-of-scope documentation is permitted.

1. How much does this change increase maintenance cost?

• Are new dependencies being added?
• Are new configuration parameters required?
• Does this need new monitoring or alerts?

2. Is the knowledge needed to understand this change shared?

• Is the PR description sufficient?
• Do code comments explain "why"?
• Have related docs been updated?

3. Do breaking changes come with a migration guide?

• Are there breaking changes in a minor version? (Flag these in review.)
• If breaking changes are included, is a migration guide bundled? (No guide = no merge.)
• Does the guide include concrete before → after rewrite examples?
• For deprecations, are the removal version and migration path documented?

4. Is the code built to accommodate change?

• Are there hardcoded values that should be configurable?
• Is configuration properly externalized?
• Is it flexible for future changes? (But avoid over-abstraction.)

Language- and Framework-Agnostic Analysis

This skill applies to any repository. Rather than relying on language-specific knowledge, focus on universal patterns:

• Entry points: main functions, index files, configured start points
• Dependency management: Manifest files — what's used and are versions pinned?
• Test conventions: test/ tests/ spec/ __tests__/ directories, file name patterns
• Configuration: .env, config/, environment variables, config file groups
• Build artifacts: Infer generated files from .gitignore