Reddit Business Idea Validator

Drive the existing pipeline in this repo (run_agent.py / agents/orchestrator.py)
end-to-end. The pipeline is fully implemented — DO NOT reimplement scraping,
analysis, or report rendering. Your job is to: (1) preflight the environment,
(2) launch the pipeline with the right parameter profile, (3) recover from
common failures using checkpoints, and (4) surface the score and report path
to the user.

Prerequisites

• Working directory: repo root D:\reddit_business_agent (or whatever the
  user's cwd is — always invoke scripts via absolute paths derived from
  <skill_dir>/..).
• .env in repo root with at minimum:
• OPENAI_API_KEY, OPENAI_BASE_URL (must end with /v1), OPENAI_MODEL
• REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_USER_AGENT
• Python 3.10+, pip install -r requirements.txt already run.
• Reddit app type must be "script" at https://www.reddit.com/prefs/apps
  (otherwise 401 on auth).

File Layout

.claude/skills/reddit-business-idea-validator/
├── SKILL.md                         # this file
├── scripts/
│   ├── preflight.py                 # Phase 1: env/deps/API checks
│   ├── run_pipeline.py              # Phase 3: non-interactive runner
│   ├── recover.py                   # Phase 4: list/inspect/resume runs
│   └── extract_report.py            # Phase 5: read run_id → report/score
└── references/
    ├── failure-recovery.md          # error → fix map
    ├── param-matrix.md              # fast / standard / deep profiles
    └── report-anatomy.md            # report sections explained

All scripts accept -h / --help. Most emit JSON or JSONL so you can parse
them programmatically. They are thin wrappers around OrchestratorAgent —
business logic stays in agents/.

Workflow

Phase 0 — Decide if this skill applies

Apply when the user provides an idea/product/niche AND wants one of:
market validation, pain-point discovery, demand estimation, sentiment,
competitive landscape, go/no-go recommendation, or a Reddit-based report.

Do NOT apply for: pure keyword research, SEO tasks, generic LLM brainstorming,
or when the user clearly wants a different data source (App Store, Amazon,
Xiaohongshu, etc.) — this pipeline only covers Reddit.

If the user does not state a data source but mentions "Reddit", " subreddit",
"post", or English-language markets, default to this skill.

Phase 1 — Preflight (always run first)

python "<skill_dir>/scripts/preflight.py"

Outputs a single JSON object. Read it and react:

Only proceed to Phase 3 when env_ok && deps_ok && reddit_ok && llm_ok are
all true. Preflight is fast (<5 s) — re-run freely.

Phase 2 — Pick a parameter profile

Default to standard. Offer the choice via AskUserQuestion if the user
hasn't specified; otherwise pick based on signals:

• "fast" / "快速" / "试试" / "smoke test" / dev iteration → fast
• default / "完整" / "正式" / "深度调研" / no signal → standard
• "尽可能多" / "最深" / "thorough" / one-shot for a real decision → deep

See references/param-matrix.md for exact numbers per profile.

Phase 3 — Run the pipeline

Launch in background, then poll output. The runner emits JSONL on stdout
(one event per line) and a final summary event you can parse.

python "<skill_dir>/scripts/run_pipeline.py" "<idea>" --profile standard

Use the Bash tool with run_in_background: true. Read incremental output
with TaskOutput. Each line is JSON; key events:

{"event":"run_started","run_id":"...","profile":"standard","idea":"..."}
{"event":"stage","step":"scrape_data","progress":0.0,"message":"执行: 抓取..."}
{"event":"stage","step":"scrape_data","progress":1.0,"message":"完成: 抓取..."}
...
{"event":"done","success":true,"report_path":"D:\\...\\reports\\<idea>_<ts>.html","score":72,"run_id":"...","execution_time":187.4}

On event:"done" with success:true, you have the report path and score —
go to Phase 5.

On event:"done" with success:false, read error and failed_step, then
jump to Phase 4 / references/failure-recovery.md.

Phase 4 — Recover from failure

Two recovery modes:

4a. Resume from checkpoint — useful when scrape or analysis succeeded
but a later step crashed (timeout, network blip):

python "<skill_dir>/scripts/recover.py" --resume-last --idea "<idea>" --profile standard

This finds the latest run_id for that idea, inspects which checkpoints
exist, and re-invokes the pipeline using existing partial results where
possible.

4b. Just list & inspect — for understanding state:

python "<skill_dir>/scripts/recover.py" --list                       # all runs
python "<skill_dir>/scripts/recover.py" --list --idea "<idea>"       # filtered
python "<skill_dir>/scripts/recover.py" --show <run_id>              # checkpoint detail

For known errors (401, quota, malformed JSON), follow references/failure-recovery.md
instead of blind retry — some failures are deterministic and need a human
fix.

Phase 5 — Surface results to the user

After event:"done":

1. Extract full result (cheap, idempotent):
   bash python "<skill_dir>/scripts/extract_report.py" --run-id "<run_id>"
   Returns JSON with report_path, score, summary, top pain points,
   opportunities, and recommendations.

2. Tell the user in chat, concisely:
   - Overall score (0-100) and one-line gut interpretation
   (≥75 strong, 50-74 promising, 30-49 weak, <30 likely no-go)
   - Top 3 pain points
   - Top 3 opportunities
   - Report absolute path — offer to open in browser
   - Run id (so they can resume later or compare)

3. Do not paste the full HTML. It's large. Summarize; the user can open
   the file.

4. Offer follow-ups: re-run with deep profile, compare with another run,
   adjust the idea wording and re-validate.

Operating Principles

• Never reimplement pipeline stages. Call run_pipeline.py.
• Always run preflight before the pipeline on a fresh session — costs
  5 seconds, saves a 10-minute failure.
• Background the pipeline. It can take 3-30 min depending on profile.
  Use run_in_background: true and poll TaskOutput; don't block the turn.
• Parse JSONL, don't regex human text. Stderr still has human logs for
  debugging — only stdout is structured.
• Be honest about scores. A 35/100 is a useful negative result. Don't
  sugarcoat; the user wants signal.
• Resume > restart. If a stage crashed after a successful scrape,
  reuse the scrape via recover.py --resume-last instead of re-scraping
  (Reddit rate limits are real).

Common Mistakes to Avoid

• Don't pass --profile fast to "be helpful" without asking — fast misses
  signal. Default is standard.
• Don't read .env keys yourself to "verify" — preflight already does it
  authoritatively.
• Don't try to pip install new packages mid-run; if preflight says deps
  missing, ask the user.
• Don't shorten the business idea when passing it through — the pipeline
  uses it as the search keyword verbatim.
• Don't run two pipelines in parallel — they share reports/ and checkpoint
  dirs and will race on filenames.

References (read on demand)

• references/failure-recovery.md — error → fix table, opened when phase 3/4 fails
• references/param-matrix.md — exact knobs per profile
• references/report-anatomy.md — what each section of the HTML report means