agentleFS
jiahao-shao1jiahao-shao1/sjh-skills/skills/project-review/SKILL.md

project-review

Skill43 starsChanged 7 months agoMITView on GitHub

Strategic project review — auto-discovers strategy docs (vision, roadmap, decisions, notes), produces five-dimension snapshot. Use for direction review, alignment check, milestone status, pre-meeting overview. Triggers: 'project review', 'strategic review', 'where is the project at', '项目全景', '审视战略', '项目现在什么状态'. Not for code/PR review.

17 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 12 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 16
  2. Distinctive:

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

    line 18
  3. Very specific:

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

    line 50
  4. Very specific:

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

    line 63
  5. Distinctive:

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

    line 65
  6. Distinctive:

    If no vision document exists, infer project goals from README (mark as inferred)

    line 75
  7. Very specific:

    If documents were found via Phase 1b auto-discovery (rather than the config file), append a recommended configuration at the end of the …

    line 125

“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 TypeSearch Paths (by priority)Purpose
Visiondocs/strategy/vision.md → docs/vision.md → VISION.mdCore positioning and assumptions
Roadmapdocs/strategy/roadmap.md → docs/roadmap.md → ROADMAP.mdMilestones and timeline
Paper Outlinedocs/strategy/paper-outline.mdPaper outline (research projects)
Related Work_index.md or all .md under docs/strategy/related-work/Related work coverage
Decisionsdocs/strategy/decisions/log.md → docs/strategy/decisions/ → docs/adr/Decision records
Meetings2 most recent .md under docs/strategy/meetings/ (exclude _template.md)Meeting notes
Experiments.claude/knowledge/experiments.mdExperiment log
ProgressHANDOFF.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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.