research

Parse the user's input:

• First argument is the task name (matches the output directory, e.g., offline-sync-bugfix)
• Remaining arguments are file paths to context documents (questions file, facts file, task description, etc.)

If no file paths are provided, auto-discover files in docs/{task-name}/:

• questions.md — required (the questions to answer)
• facts.md — optional (codebase implementation context)

If no questions file is found in arguments or auto-discovery, ask the user for one.

Methodology rationale

This skill implements an Explanatory Sequential research design (research.md: Mixed Methods):

1. Code research first — establishes what the codebase actually does (confirmatory)
2. External research second — informed by code findings, enabling triangulation
3. Synthesis third — critical analysis using accumulated evidence from both rounds

Additional methods applied:

• Triangulation — external agents receive code findings to cross-reference
• Theoretical sampling (Grounded Theory) — agents report NEW_QUESTIONS discovered during research
• Confirmation bias mitigation — code agents explicitly search for counter-evidence
• Confidence ratings — map to evidence quality (internal/external validity)
• Thematic organization — synthesis groups findings by conceptual themes, not just question order

Phase 1 — Read & classify questions

Read all input files. Identify the questions document by its structure (contains ## Phase sections or similar question groupings with bullet-pointed questions).

Build a research brief — a compact summary (max ~500 words) capturing:

• What the task is (feature, bugfix, refactor, etc.)
• Key technical areas involved
• What the codebase context reveals (from facts.md or equivalent)
• Scope of questions to answer

Parse the questions document into four groups. If it follows the /questions output structure, map directly:

If the questions document uses a different structure, classify each question by whether it requires:

• Human judgment or authority → User-required
• Source code exploration → Code-answerable
• Web/docs/domain research → External-answerable
• Cross-cutting synthesis of multiple sources → Critical analysis

Count total questions and questions per group. Report counts to the user.

Phase 2 — Interactive user Q&A

Extract all user-required questions. These cannot be answered by agents — they need domain knowledge or decision-making authority.

Ask these questions to the user one at a time. For each question:

1. Present the question clearly, including its sub-category for context (e.g., "Intent & Motivation: Why does this task exist?")
2. Wait for the user's response
3. If the user replies with "skip", "idk", "I don't know", "pass", or similar — mark the question as skipped and move on
4. Otherwise, record the user's answer verbatim

After all questions are asked, compile the results:

• Answered questions — store as Q/A pairs
• Skipped questions — these will appear as checkboxes in the final output

Write a user answers addendum to include in the research brief. Format:

## User Answers (from stakeholder Q&A)

### {Sub-category}
**Q:** {question}
**A:** {user's answer}

### Skipped
- {skipped question 1}
- {skipped question 2}

Append this addendum to the research brief built in Phase 1. This enriched brief is what every agent receives in subsequent phases — user answers directly inform the research.

Tell the user: "Got it — {N} answered, {S} skipped. Starting research on the {M} researchable questions."

Phase 3 — Parallel code research

For each sub-category in the code-answerable group (e.g., "Architecture & Patterns", "Dependencies & Coupling"), spawn a code-researcher agent:

task_name: {task-name}
category: {sub-category name}
questions: {questions in this sub-category, as a bullet list}
context_brief: {research brief from Phase 1}
hint_paths: {relevant paths from context docs, or "none"}

Use the Agent tool with subagent_type: "code-researcher". Spawn all sub-category agents in parallel.

After all agents complete, collect from each agent's response:

• ANSWERED, UNANSWERED, and PARTIAL tallies
• NEW_QUESTIONS discovered during code research
• Note which fragment files were written (docs/{task-name}/research-code-*.md)

Report progress: "Code research complete. {X} answered, {Y} partial, {Z} unanswered. {W} new questions discovered."

Phase 4 — Parallel external research

For each sub-category in the external-answerable group, spawn an ext-researcher agent:

task_name: {task-name}
category: {sub-category name}
questions: {questions in this sub-category, as a bullet list}
context_brief: {research brief from Phase 1}
code_findings_path: {comma-separated paths to research-code-*.md fragments from Phase 3, or "none"}

Use the Agent tool with subagent_type: "ext-researcher". Spawn all sub-category agents in parallel.

After all agents complete, collect from each agent's response:

• ANSWERED, UNANSWERED, and PARTIAL tallies
• NEW_QUESTIONS discovered
• CONFLICTS between external sources and code findings
• Note which fragment files were written (docs/{task-name}/research-ext-*.md)

Report progress: "External research complete. {X} answered, {Y} partial, {Z} unanswered. {W} conflicts found."

Phase 5 — Synthesis: Critical Analysis

Read all fragment files from Phases 3 and 4:

• Glob docs/{task-name}/research-code-*.md
• Glob docs/{task-name}/research-ext-*.md

For each critical analysis question, answer it using the accumulated evidence:

1. Draw on findings — cite specific answers from code and external research
2. Triangulate — where do code findings and external sources agree? Where do they conflict?
3. Pre-mortem (Klein) — "Given what we now know, how could this change fail?"
4. Consider-the-opposite (Lord et al.) — "What would have to be true for a different approach to be better?"
5. Rate confidence — based on the strength of supporting evidence

Write synthesis findings to docs/{task-name}/research-synthesis.md with the same Q/A format as agent fragments.

Phase 6 — Compile final research document

1. Glob docs/{task-name}/research-*.md to find all fragment files
2. Read every fragment
3. Combine into docs/{task-name}/research.md with the structure below
4. Deduplicate findings that appear in multiple fragments
5. Preserve all source references and citations
6. Delete all fragment files

Output structure

# {Task Name} — Research Findings

> **Task:** {brief description from research brief}
> **Context sources:** {list of input files}
> **Questions answered:** {answered count} of {total count}

---

## User & Stakeholder Context

*These questions needed human judgment or authority. Answered questions show
the user's response inline. Skipped questions remain as checkboxes.*

### {Sub-category}

**Q: {answered question}**
**A:** {user's verbatim answer}

- [ ] {skipped question} *(why it matters)*

---

## Codebase Findings

*Answers derived from reading source code.*

### {Sub-category}

**Q: {question}**
**Confidence:** HIGH | MEDIUM | LOW

{Answer with file:line references}

Evidence:
- `path/to/file.py:123` — {what this shows}

---

## External Research Findings

*Answers derived from documentation, web sources, and domain expertise.*

### {Sub-category}

**Q: {question}**
**Confidence:** HIGH | MEDIUM | LOW
**Source tier:** {Official docs | Standard | Blog | Community}

{Answer with [source] citations}

**Triangulation:** {alignment or conflict with code findings}

---

## Critical Analysis

*Synthesis of code and external findings applied to higher-order questions.*

### {Sub-category}

**Q: {question}**

{Analysis drawing on evidence from prior sections, with cross-references}

---

## Conflicts & Tensions

*Areas where codebase reality and external best practices diverge.
Each conflict requires an explicit design decision.*

| Topic | Code does | External recommends | Implication |
|-------|-----------|-------------------|-------------|
| {topic} | X (`file:line`) | Y ([source]) | {what this means for the task} |

---

## Discovered Questions

*New questions that emerged during research — not in the original set.
These represent "theoretical sampling": evidence-driven question generation.*

### Needs User Input
- Question *(why it matters — what finding triggered it)*

### Needs Further Research
- Question *(why it matters — what finding triggered it)*

---

## Research Gaps

*Questions that could not be fully answered and why.*

| Question | Status | Reason |
|----------|--------|--------|
| {question} | UNANSWERED | {no relevant code | no authoritative source | conflicting info} |
| {question} | PARTIAL | {what was found; what's still missing} |

---

## Confidence Summary

| Section | HIGH | MEDIUM | LOW | Unanswered |
|---------|------|--------|-----|------------|
| Codebase | {n} | {n} | {n} | {n} |
| External | {n} | {n} | {n} | {n} |
| Critical Analysis | {n} | {n} | {n} | {n} |
| **Total** | {n} | {n} | {n} | {n} |

If any section has no content (e.g., no conflicts found, no discovered questions), omit that section entirely — no empty sections.

Phase 7 — Report

Tell the user the output is at docs/{task-name}/research.md and provide:

• Total questions: {count}
• Answered (HIGH/MEDIUM/LOW): {counts}
• User-answered in Q&A: {count}
• User-skipped (still needs input): {count}
• Unanswered / gaps: {count}
• Conflicts found: {count}
• New questions discovered: {count}