| name | research |
| description | Conducts project assessment and topic investigation. Use when stepping back to understand the big picture or when the user asks "what's the current state?" Produces state assessments, research findings with ranked options, or vision change proposals. Not for problem discovery that should author a brief (use pitch), multi-agent coordination (use orchestration), or implementation. |
Research
Patterns for zooming out, investigating topics, and evolving project direction.
Contents
- Critical Rules
- Verification
- Quick Reference
- Topics
- Input Parsing
- Confidence Hierarchy
- Research Modes
- Related Skills
Input: $ARGUMENTS
Critical Rules
Always
- Interview before researching
- Check project context first
- Cite sources with confidence levels
- Present options, let user decide
- Get approval before editing VISION
- Log invocation first:
loaf journal log "skill(research): <topic or mode>"
- Log findings to the project journal:
loaf journal log "discover(scope): summary of finding"
Never
- Edit VISION without explicit approval
- Research indefinitely (set time bounds)
- Ignore existing project decisions
- Present research as implementation plan
- Skip the interview step
Verification
- Interview step was completed before research began
- All findings cite sources with confidence levels (High/Medium/Low)
- VISION.md was not modified without explicit user approval
Quick Reference
| Input Pattern | Mode |
|---|
| Empty / "project state" / "catch me up" | State Assessment |
| Topic or question | Topic Investigation |
| "let's brainstorm" / "ideas for X" | Redirect — user entry intent belongs to pitch (generative stance is an agent technique via explore/brainstorm, not this skill's front door) |
| "should we change direction?" / "update VISION" | Vision Evolution |
Topics
| Topic | Template | Use When |
|---|
| State Assessment | state-assessment.md | Producing a project state overview |
| Report | report.md | Writing research, audit, analysis, or council output |
Input Parsing
Parse $ARGUMENTS to determine mode:
| Input Pattern | Mode |
|---|
| Empty / "project state" / "catch me up" | State Assessment |
| Topic or question | Topic Investigation |
| "let's brainstorm" / "ideas for X" | Redirect to pitch for human entry; do not open research's brainstorming mode as a pitch substitute |
| "should we change direction?" / "update VISION" | Vision Evolution |
Confidence Hierarchy
Prioritize sources in this order:
- Project context (highest) -- VISION.md, ARCHITECTURE.md, the project journal, codebase patterns
- Authoritative docs -- Context7, official docs, RFCs
- Community knowledge -- Stack Overflow (verified), GitHub issues, expert blogs
- General web (lowest) -- Search results, unverified sources
Always check project context first. Rate findings: High (official/verified), Medium (authoritative, consistent), Low (community, single reference).
Research Modes
State Assessment
Trigger: Empty input, "project state", "catch me up"
- Read project documents: VISION.md, STRATEGY.md, ARCHITECTURE.md
- Check ideas with
loaf idea list --json and issues with loaf issue list --json (or loaf issue export for the full graph)
- Review recent journal activity with
loaf journal recent --json and loaf journal context
- Check recent commits:
git log --oneline -20
- Synthesize following state-assessment template
Topic Investigation
Trigger: Specific topic or question
- Interview (one question at a time, with a recommendation, using your harness's structured question tool if it has one): what are you trying to understand? What context do you have? What decision will this inform?
- Check project context first (ADRs, ARCHITECTURE, the project journal)
- Apply confidence hierarchy for external sources
- For a transient review artifact, use
loaf report generate when an existing
SQLite-backed export kind fits; for authored long-form research, create a
Markdown report following the report template
Output: generated report Markdown to stdout, or an authored report at
.agents/reports/{YYYYMMDD}-{HHMMSS}-research-{slug}.md when a durable prose
artifact is explicitly needed.
For SQLite-backed report state, use loaf report create, loaf report finalize, and loaf report archive. Do not hand-edit report lifecycle
frontmatter to represent operational status.
Entry-intent redirect (not a research mode)
Trigger: "Let's brainstorm" / "Ideas for X" / raw concept entry
User-facing entry for a new concept is pitch (problem-discovery brief). Do not treat research as the brainstorm front door. When generative expansion is needed mid-research or mid-pitch, the agent may use the explore/brainstorm techniques — they are not substitutes for the pitch front door.
Vision Evolution
Trigger: "Should we change direction?" / "Update VISION"
- Gather evidence (journal entries, feedback, market changes)
- Identify what's changed since last VISION update
- Propose specific changes with rationale
- Get user approval before any edits
Related Skills
- pitch - Human problem-discovery when research crystallizes a concept that needs a brief
- orchestration - For acting on research findings
- explore / brainstorm - Agent techniques for divergent inquiry (not user front doors)
- reflect - For updating strategy post-shipping
- architecture - For making technical decisions
- strategy - For discovering strategic context
Artifact Naming
Name every artifact you create for what it is, never for the work unit that produced it: the containing directory or the issue already records that provenance. Put the source in a front-matter field, not the filename. Versions and timestamps are identity and stay. See the foundations skill for the full rule; loaf check --hook artifact-names enforces it at commit.
