| name | scan |
| description | Quick scan of a project — gather metadata, key metrics, lifecycle stage classification, and first impressions. Supports remote URLs, local directories, and local files.
|
Research-Forge — Scan
Quick reconnaissance scan of a project to gather key signals and classify its lifecycle stage before a full analysis.
Command: /research-forge:scan
Usage:
/research-forge:scan <target> [--lang zh|en]
Target can be a URL, local directory path, or local file path.
Scan Logic:
1. Detect Target Type & Fetch Project Metadata
Remote URL:
- Use WebFetch to retrieve the project's README, GitHub API data, or landing page.
- Extract: name, description, language, license, creation date, last commit date.
Local Directory:
- Read README (README.md, README.rst, README.txt — whichever exists).
- Read package manifest (package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml, build.gradle, etc.).
- Glob project structure to understand scope: source files, test files, config files, docs.
- Check git history:
git log --oneline -20, git remote -v, git shortlog -sn.
- Extract: name (from manifest or directory name), description, language, license, creation date (first commit), last commit date.
Local File:
- Read the file. If it's a README or spec doc, extract project info directly.
- If it's source code, identify the parent project directory and treat as Local Directory.
2. Quantitative Signals
Remote projects:
- Popularity: Stars, forks, watchers count and growth trajectory.
- Activity: Commit frequency (last 30/90/365 days), open vs. closed issues ratio, PR merge velocity.
- Community: Number of contributors, contributor concentration (bus factor), Discord/Slack links.
- Dependencies: Key dependencies, number of dependents (who uses this?).
Local projects:
- Structure: Total file count, source file count, test file count, lines of code estimate.
- Activity: Commit frequency from git log, number of contributors, branch count.
- Dependencies: Key dependencies from manifest, dependency count, outdated signals.
- Quality signals: Presence of CI config, linter config, test framework, documentation.
3. Stage Classification (MANDATORY)
Classify the project into a lifecycle stage per the Stage Model in the research-forge framework — this determines how the entire downstream analysis is weighted:
- S0 — Concept / Pre-launch: No working product or prototype only; no real users; no releases or v0.0.x.
- S1 — PMF Search (0→1): Working product, early adopters, rapid iteration, little/no revenue.
- S2 — Scaling (1→10): Retention evidence, monetization live or forming, sustained growth, team beyond founders.
- S3 — Market Leadership (10→100): Category leader/top-3; third parties build on it; de-facto default choice.
State the classification with:
- 2-3 pieces of converging evidence (age, releases, adoption trajectory, revenue signals, ecosystem signals)
- A confidence level (High / Medium / Low)
- When torn between two stages, pick the earlier one — under-claiming maturity is the safer error.
4. Qualitative First Impressions
- README quality: Is it clear, professional, well-structured?
- Documentation: Does it exist? Is it maintained?
- Positioning: How does the project describe itself? What problem does it claim to solve?
- Code organization: Is the structure clean and conventional for the language/framework?
5. Output Format
Produce a concise snapshot card:
Project Snapshot: [Name]
Target: [URL or Path]
Scan Date: [Date]
Quick Stats:
[Remote] Stars: X | Forks: X | Contributors: X
[Local] Files: X | Source: X | Tests: X
Last Commit: [Date] | Open Issues: X
Language: [Lang] | License: [License]
Lifecycle Stage: [S0/S1/S2/S3 — Name] (Confidence: High/Medium/Low)
Evidence: [2-3 converging signals]
One Question for this stage: [the stage's core question]
First Impressions:
[2-3 sentence summary]
Key Signals:
[Bullet list of notable positive/negative signals]
Recommended Next Step:
[ ] Full analysis warranted → /research-forge:analyze <target>
[ ] Compare with competitors → /research-forge:compare <target> <competitor>
[ ] Not worth pursuing → [reason]
