project-review

Project Review

Reads the project's strategy document ecosystem and generates a panoramic snapshot. Useful before team meetings, when feeling lost about direction, or for periodic retrospectives — helps you quickly understand where the project is and where it should go.

Execution Skeleton

Phase 1: Load Document Manifest

First check if the project has an explicit configuration: read docs/strategy/.review-sources.md.

If it exists, read each path listed — the project maintainer has already specified which documents constitute the "strategic picture", no guessing needed.

If it doesn't exist, fall through to Phase 1b (auto-discovery).

Configuration Format (docs/strategy/.review-sources.md)

# Project Review Sources

## Core
- docs/strategy/vision.md
- docs/strategy/roadmap.md
- docs/strategy/paper-outline.md

## Decisions
- docs/strategy/decisions/log.md

## Related Work
- docs/strategy/related-work/_index.md

## Meetings (latest 2)
- docs/strategy/meetings/

## Experiments
- .claude/knowledge/experiments.md

## Progress
- HANDOFF.md

Each entry is a path relative to project root. Directory paths (ending with /) mean "read the 2 most recently modified files in that directory". Lines starting with # are section headers for grouping.

Phase 1b: Auto-Discovery (fallback when no config exists)

Search the following paths, excluding third_party/, node_modules/, .venv/, vendor/:

Document Type	Search Paths (by priority)	Purpose
Vision	docs/strategy/vision.md → docs/vision.md → VISION.md	Core positioning and assumptions
Roadmap	docs/strategy/roadmap.md → docs/roadmap.md → ROADMAP.md	Milestones and timeline
Paper Outline	docs/strategy/paper-outline.md	Paper outline (research projects)
Related Work	_index.md or all .md under docs/strategy/related-work/	Related work coverage
Decisions	docs/strategy/decisions/log.md → docs/strategy/decisions/ → docs/adr/	Decision records
Meetings	2 most recent .md under docs/strategy/meetings/ (exclude _template.md)	Meeting notes
Experiments	.claude/knowledge/experiments.md	Experiment log
Progress	HANDOFF.md (project root)	Current progress

Use exact paths with sequential fallback — avoid **/ recursive globs, which tend to match files under third_party/ and produce noise.

If none of the above paths exist, prompt the user:

"No strategy documents found. Consider creating docs/strategy/.review-sources.md to specify document locations, or create vision.md and roadmap.md under docs/strategy/."

Phase 2: Five-Dimension Analysis

Generate analysis based on the discovered documents. Only produce a dimension when supporting documents exist — skip dimensions without data, because speculation is more dangerous than silence.

1. Vision Check

• Is current work aligned with core objectives / assumptions?
• Which assumptions are validated, challenged, or untested?
• If no vision document exists, infer project goals from README (mark as inferred)

2. Roadmap Status

• Progress overview (done / in-progress / planned)
• Current phase's position in the overall roadmap
• Any work that deviates from the plan

3. Bottleneck Identification

• Extract current blockers from experiment results and decision records
• Distinguish technical bottlenecks (e.g., unstable API) from research/business bottlenecks (e.g., invalidated assumptions)

4. Related Work Gap (research projects)

• Which topics lack related work coverage?
• Are there newly published works that need attention?

5. Next Steps

• Recommendations based on the above analysis
• Priority ordering: urgent vs. important

Phase 3: Output

========================================
        PROJECT REVIEW SNAPSHOT
        <project-name> | YYYY-MM-DD
========================================

## 1. Vision Check
...

## 2. Roadmap Status
| ID | Milestone | Status | Notes |
...

## 3. Bottleneck Identification
...

## 4. Related Work Gap
...

## 5. Next Steps
1. ...
2. ...
3. ...

========================================

First-Use Onboarding

If documents were found via Phase 1b auto-discovery (rather than the config file), append a recommended configuration at the end of the output so the user can quickly create .review-sources.md:

Tip: Create docs/strategy/.review-sources.md to precisely specify document
locations and avoid false matches. Recommended config:

<generate config content based on actually discovered files>

Constraints

• Read-only — do not modify any documents. This skill's value is providing perspective, not making decisions for the user.
• Output to terminal — do not create files unless the user explicitly asks to save. Avoid "documents writing documents" noise.
• Follow the user's language — respond in whichever language the user uses.
• Skip dimensions that lack supporting documents — silence is more valuable than false confidence.
• This skill does not replace weekly-report (for reporting) or meeting-slides (for presentations) — it's for personal/team strategic reflection.