Research Explore

Explore Workflow

One skill for the three ways to reduce the unknown: read the web, build a throwaway, or learn a codebase.

Pick your mode

| Situation | Mode | Jump to | |-----------|------|---------| | Don't know the right solution / library / pattern yet — compare via docs | WEB | [Mode WEB](#mode-web) | | Need to validate a technical assumption by building a prototype | SPIKE | [Mode SPIKE](#mode-spike) | | Joined / returned to a codebase and need to ramp up | ONBOARDING | [Mode ONBOARDING](#mode-onboarding) |

Flow: WEB (read) → if still unsure, SPIKE (build to validate) → if accepted, /feature-build (NEW) to implement properly.

• ❌ Already know the approach → /feature-build (NEW) or /fix-bug
• ❌ Debugging a known bug → /fix-bug (DEEP mode)
• ❌ Generate a full docs site → /docs-sync

Read Architecture First (all modes)

Detect stack via ~/.claude/architecture/_shared/stack-detection.md. Read ddd-architecture.md + the stack doc — architecture context speeds up everything below.

---

---

Mode WEB

Research solutions on the web for a specific problem. Output: a written recommendation with sources. Never implement — wait for user approval, then hand off to /feature-build (NEW) or Mode SPIKE.

ARGUMENTS: (optional) topic to research. If omitted, infer from current conversation context.

When to use

• ✅ You don't know the right solution / library / pattern yet
• ✅ Need to compare multiple approaches before committing
• ✅ Stack / framework changed, best practices may have shifted
• ❌ You already know the approach → /feature-build (NEW) or /fix-bug (QUICK)
• ❌ Want to validate by building → Mode SPIKE

Workflow

IDENTIFY → DETECT STACK → SEARCH → SYNTHESIZE → PROPOSE

Step 1: IDENTIFY

• Arg provided: use it as the topic; if too broad, narrow using project context before any search.
• No arg: analyze conversation (recent messages, open file, task), summarize the problem back to user, get confirmation before burning search budget.

Research budget guide

| Scope | Budget | When to stop | |-------|--------|--------------| | Quick lookup (API behavior, error meaning) | 2-3 queries | First authoritative source confirms | | Solution comparison (2-3 options) | 5-8 queries | Each option has ≥2 independent sources | | Deep dive (new pattern, unfamiliar domain) | 10-15 queries | Recommendation is defensible |

Hard cap: 15 queries without converging → stop, report what's found + ask user to narrow.

Gate

• [ ] Problem statement confirmed (no-arg mode) · Scope narrow enough · Budget agreed (default 5-8)

Step 2: DETECT STACK

Capture for filter use: language + version, framework + version, architecture pattern (DDD / hexagonal), hard constraints (license, runtime, infra).

Step 3: SEARCH

Strategy

1. Broad first — overview, common approaches, "X vs Y" comparisons
2. Deep dive — official docs, GitHub issues, release notes, authoritative blogs
3. Counter-search — actively look for criticism / failure stories of the leading option

Source priority

| Priority | Source | Weight | |----------|--------|--------| | 1 | Official docs (current version) | Highest | | 2 | GitHub issues / release notes (project itself) | High — quirks + known bugs | | 3 | Stack Overflow accepted answers (high score, recent) | Medium-high | | 4 | Authoritative blogs (framework authors, well-known engineers) | Medium | | 5 | Tutorials, course material | Low — risk of outdated patterns | | 6 | AI-generated content | Skip unless verifiable against #1-#4 |

Search tips

• Prefer English queries — richer index; supplement with framework's primary docs language
• Include library + version when version-sensitive; quote exact error messages
• Cross-validate ≥2 independent sources before concluding

When sources conflict

1. Different versions? → trust the one matching project version
2. One is official docs? → trust official
3. Different dates, same authority? → trust newest, note the change
4. Same date, different authority? → trust higher-authority per priority table
5. Cannot resolve? → present both, recommend lower-risk, explain trade-off

Always note the conflict in the report — don't silently pick one side.

Gate

• [ ] ≥2 independent sources per option · Sources _handler` |

| Add business logic | domain//usecases | | Add a DB query | infrastructure/database/_store | | Add a domain event | domain//events + register in event bus | | Add a test | *_test.go next to the source file |

Conventions

• Error handling / Logging / Config / Branch + commit

Gotchas

• {anything surprising}

### Gate
- [ ] 1-page mental model written · "Where to find things" covers ≥5 tasks · ≥1 gotcha documented

## Phase 4: GUIDE — first commit checklist

Unblock the first real change. Pick a "quick win" (≤30 min, one layer, clear success criterion).

- [ ] Local env runs: build + lint + tests all green from a fresh clone
- [ ] Made the change in the right layer (per Phase 3 table)
- [ ] Added or updated 1 test
- [ ] Followed naming + error-handling conventions
- [ ] Commit message matches project style (`git log --oneline`)
- [ ] PR description follows template (`.github/PULL_REQUEST_TEMPLATE.md`)
- [ ] Self-reviewed with `/review-code` (SELF mode) before opening PR

**Who to ask:** architecture → tech lead from git shortlog · domain X → recent committer · infra/deploy → ops contact from README.

### Gate
- [ ] Local env verified · First "quick win" task picked · First-commit checklist printed

## Hard Rules (ONBOARDING)
- **Read one module end-to-end before reading 10 partially** — the trace teaches more than skimming.
- **Capture gotchas as you find them** — they vanish from memory in days.
- **First commit ≤30 min** — bigger first changes get rabbit-holed.
- **Don't refactor on day 1** — earn context before changing conventions.

---
---

## Related Skills

| When | Use |
|------|-----|
| Ready to implement after WEB / SPIKE | `/feature-build` (NEW mode) |
| First bug fix to learn the codebase | `/fix-bug` |
| Write up research / ADR / onboarding doc | `/docs-sync` |
| Generate full doc site after onboarding | `/docs-sync` |
| Self-review first commit | `/review-code` (SELF mode) |

## Recommended Agents

| Mode / Phase | Agent | Purpose |
|--------------|-------|---------|
| WEB search | `@docs-writer` | Frame output as design note |
| WEB synthesize | `@api-designer`, `@security-audit`, `@perf-optimizer` | API / security / perf depth |
| SPIKE define / evaluate | `@clean-architect` | Frame the question + architecture impact |
| SPIKE prototype | Stack-specific dev agent | Build the POC |
| ONBOARDING scan / analyze | `@clean-architect`, `@code-reviewer` | Architecture + conventions |
| EXPLAIN / GUIDE | `@docs-writer` | 1-page overview + first-commit checklist |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [phuthuycoding](https://github.com/phuthuycoding)
- **Source:** [phuthuycoding/moicle](https://github.com/phuthuycoding/moicle)
- **License:** MIT

Install and usage instructions live in the source repository linked above.