mxyhi/ok-skills / autoresearch
autoresearch
FlaggedAutonomous iteration loop: modify, verify, keep/discard against any metric
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 7.8 KB |
| agents/openai.yaml | config | 250 B |
| autoresearch.md | markdown | 4.8 KB |
| debug.md | markdown | 4.0 KB |
| evals.md | markdown | 5.0 KB |
| fix.md | markdown | 4.3 KB |
| improve.md | markdown | 6.0 KB |
| learn.md | markdown | 7.9 KB |
| plan.md | markdown | 2.8 KB |
| predict.md | markdown | 3.7 KB |
| probe.md | markdown | 4.8 KB |
| reason.md | markdown | 4.7 KB |
| references/orchestrator-routing.md | markdown | 6.8 KB |
| references/predict-personas.md | markdown | 3.1 KB |
| references/reason-judge-protocol.md | markdown | 3.4 KB |
| references/security-checklist.md | markdown | 3.4 KB |
| regression.md | markdown | 9.3 KB |
| scenario.md | markdown | 4.1 KB |
| scripts/orchestrate.shexecutable | script | 18.5 KB |
| scripts/score-regression.shexecutable | script | 7.5 KB |
| security.md | markdown | 4.6 KB |
| ship.md | markdown | 3.8 KB |
improve.md
View on GitHub---
name: autoresearch:improve
description: "Research ICP challenges, discover improvements, generate PRDs"
argument-hint: "[Goal: <text>] [--icp <text>] [--discover] [--no-discover] [--seeds <categories>] [--depth shallow|standard|deep] [Iterations: N] [--evals]"
---
EXECUTE IMMEDIATELY.
## Parse Arguments
Extract from $ARGUMENTS:
- `Goal:` — product area to improve (or full $ARGUMENTS if no keyword)
- `--icp` or `ICP:` — ideal customer profile description
- `--discover` — force inline codebase scan even when context exists
- `--no-discover` — skip auto-discover, warn instead
- `--seeds <categories>` — override default research category seeds
- `--depth` — shallow (5 iterations), standard (15), deep (30)
- `--features` — comma-separated feature names to pre-select for PRD generation
- `Iterations:` or `--iterations` — default 15. "unlimited" for unbounded.
- `--evals`, `--evals-interval N`
If upstream `handoff.json` exists in CWD → read it. Map source findings to default seed categories:
- probe → ICP challenges, UX & experience
- predict → Competitor gaps, Revenue & growth
- debug/security → Competitor gaps, ICP challenges
- Override with `--seeds`.
## Setup (if Goal or ICP missing)
request_user_input (single batch):
Q1 (Goal): "What product area to improve?" — open text
Q2 (ICP): "Who is your ideal customer?" — open text describing target buyer/user
Q3 (Pain points): "Top 3 pain points your customers face?" — open text
Q4 (Competitors): "Key competitors?" — open text, or "skip"
Q5 (Depth): "How deep?" — shallow (5 iterations, quick scan), standard (15, recommended), deep (30+, exhaustive)
If all provided inline → skip.
## Phase 1: Product Context
Resolve product context (priority chain):
1. Learn summary (`autoresearch/learn-*/summary.md`, most recent) → read it
2. README.md (≥500 chars, non-boilerplate) → extract product description
3. `package.json` / `pyproject.toml` / `Cargo.toml` description (≥10 chars) → use it
4. If ALL above absent AND NOT `--no-discover` → auto-discover: scan 10 key files (manifest, routes, models, config), cap 1500 tokens
5. If `--discover` → force scan regardless of above
6. If nothing found → warn: "No product context. Run `$autoresearch learn --mode summarize` for better results."
## Phase 2: Research Loop
Create output directory: `autoresearch/improve-{YYMMDD}-{HHMM}/`
TSV header: `# metric_direction: higher_is_better`
Columns: `iteration|timestamp|category|research_question|status|source|insight_problem|insight_mechanism|confidence|classification`
**5 research categories:**
1. ICP challenges — pain points, jobs-to-be-done, unmet needs
2. Competitor gaps — weaknesses, missing features, technical differentiators
3. Market trends — timing signals, emerging patterns, regulatory shifts
4. UX & experience — interaction models, onboarding, retention mechanics
5. Revenue & growth — pricing, acquisition, monetization, upsell/expansion
**Iteration protocol:**
- Reserve first 5 iterations: one per category (forced breadth)
- Remaining iterations: target categories with richest signal
- Per iteration: form research question → WebSearch → synthesize → normalize to canonical insight schema → classify (new/extension/duplicate) → tag confidence (HIGH: 3+ sources, MEDIUM: 2, LOW: 1) → cross-check against codebase → log
- **Saturation:** net-new insights < 2 for 3 consecutive non-reserved iterations → SATURATED, exit loop
- Hard ceiling (Iterations flag) as infinite-loop guard
**Insight schema:** `{problem: 10-word canonical form, affected_persona: ICP segment, proposed_mechanism: how to address, expected_outcome: what success looks like}`
**Classification:** New = novel {problem, persona} pair. Extension = same pair, different mechanism. Duplicate = same pair + mechanism → skip.
### Eval Checkpoint
If --evals: check if current_iteration % interval == 0 → run checkpoint.
Print: `--- Eval Checkpoint (iterations {X}-{Y}) ---\nInsights: {total} (+{new}) | Categories: {covered}/5 | Saturation: {window}/3\n{recommendation}\n---`
## Phase 3: Feature Ranking + Selection
1. **ICP binary gate** — filter insights not serving the stated ICP
2. **3-tier bucketing** — Must-have / Nice-to-have / Moonshot
3. **Pairwise ranking** within Must-have tier only (cap 7-10 items)
4. **2-sentence rationale** per item citing research evidence
5. **Confidence indicator** per item (HIGH / MEDIUM / LOW)
Write `improvement-plan.md` with full tiered ranking.
request_user_input (multi-select): present tiered list, user selects which features become PRDs.
If `--features` provided → pre-select matching items, still show for confirmation.
## Phase 4: PRD Generation
Per selected feature, write `prd-{feature-slug}.md`:
- Top disclaimer: "Auto-generated from research findings. DECISION NEEDED items and LOW-confidence sections require your judgment."
- Problem statement (from research evidence chain)
- User stories (from ICP + persona data)
- Requirements (functional + non-functional, MoSCoW from tier)
- Acceptance criteria
- Technical approach (from codebase context, framed as "suggested starting points")
- Risks + confidence (evidence tiers: primary = codebase, secondary = web research)
- Success metrics
- `DECISION NEEDED` markers for unresolvable tradeoffs
- `Open Questions` section
Write `research-findings.md` — all insights with citations + confidence.
Write `summary.md` — overview, research stats, category coverage, saturation status.
## Summary
Print: total iterations, insights discovered (new/extension), categories covered, saturation status, PRDs generated, output directory path.
## Eval Summary (--evals flag)
If --evals: write `evals-summary.md` to output directory with full analysis.
## Handoff
Write `handoff.json`: version "2.1.0", source "improve", timestamp, status (COMPLETE|SATURATED|USER_INTERRUPT|BOUNDED|ERROR), results_tsv path, findings = improvements with tier + confidence + prd_path, config{goal, icp, depth, categories_explored, insights_total, prds_generated}.
Improve is a terminal emitter — no downstream chain invocation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |