Structured Research

Structured Research

When to Use

Use this skill when tasked with researching a topic, evaluating options, or gathering information to support a decision.

Output Template

Every research deliverable must follow this structure:

# Research: [Topic]

## Summary
[2-3 sentence executive summary of findings]

## Key Findings
1. [Most important finding — one sentence]
2. [Second most important finding]
3. [Third most important finding]

## Detailed Notes

### [Subtopic A]
- [Fact or observation]. Source: [reference]
- [Fact or observation]. Source: [reference]
- Unverified: [claim that could not be confirmed]

### [Subtopic B]
- [Fact or observation]. Source: [reference]

## Sources
| # | Source | Type | Reliability | Notes |
|---|--------|------|-------------|-------|
| 1 | [name/URL] | [doc/code/article/manpage] | [High/Medium/Low] | [brief note] |
| 2 | ... | ... | ... | ... |

## Open Questions
- [Question that remains unanswered]
- [Area needing further investigation]

Procedure

1. Define the Research Question

# Read the task to extract the research question
TASK_ID="$1"
bash /home/shared/scripts/task.sh get "$TASK_ID" | jq -r '.description'

Write down:

• The specific question to answer
• Who will use this research (architect? coder? planner?)
• What decision this research supports

2. Gather Information from Available Sources

Search the codebase:

TOPIC="authentication"

# Find relevant files
rg -l "$TOPIC" ~/workspace/ /home/shared/ 2>/dev/null | head -20

# Find relevant documentation
find ~/workspace/ /home/shared/ -name '*.md' -exec grep -l "$TOPIC" {} \; 2>/dev/null

# Check configuration files
find ~/workspace/ /home/shared/ -name '*.json' -o -name '*.yaml' -o -name '*.toml' \
  | xargs grep -l "$TOPIC" 2>/dev/null

Read man pages and help text:

# For CLI tools
man $TOOL_NAME 2>/dev/null | head -100
$TOOL_NAME --help 2>&1 | head -50

Read existing documentation:

# Check for docs in the workspace
find ~/workspace/ -name 'README*' -o -name 'ARCHITECTURE*' -o -name 'DESIGN*' \
  | while read f; do echo "=== $f ==="; head -30 "$f"; done

3. For Each Claim, Note the Source

Every factual statement must be attributed:

• File path and line number for code references
• Document name for documentation references
• Tool output for empirical observations
• "Unverified:" prefix for claims that cannot be confirmed from available sources

4. Flag Uncertainty

Use these prefixes consistently:

• No prefix: confirmed from authoritative source
• Unverified: claim found in one non-authoritative source
• Conflicting: sources disagree (cite both)
• Inferred: logical deduction not directly stated anywhere

5. Write the Research Document

RESEARCH_FILE="/home/shared/research-$(date +%Y%m%d)-${TOPIC}.md"

cat > "$RESEARCH_FILE" <<'EOF'
# Research: [Topic]

## Summary
...

## Key Findings
...

## Detailed Notes
...

## Sources
...

## Open Questions
...
EOF

echo "Research written to: $RESEARCH_FILE"

6. Register as Artifact

bash /home/shared/scripts/artifact.sh register \
  --name "research-${TOPIC}" \
  --type "research" \
  --path "$RESEARCH_FILE" \
  --description "Structured research on $TOPIC"

Quality Checklist

• Every factual claim has a cited source
• Uncertain claims are prefixed with "Unverified:" or "Inferred:"
• Conflicting information is noted with both sources
• Key Findings are ordered by importance
• Open Questions identify specific gaps, not vague areas
• Sources table includes reliability assessment
• Document is written for the intended audience (technical depth matches reader)