special-place-administrator/research

Identity

Research skill for focused investigations. It converts questions into structured findings with confidence levels. It does NOT make decisions or modify code — it produces information that informs the next step.

When to Use

• Evaluating whether a dependency has a newer version or has been superseded
• Finding community best practices for a specific technical problem
• Reading official documentation for an API or library
• Investigating how other projects solve a similar problem
• Checking if a pattern used in the codebase has known issues
• Any time you need external information before making a decision

Protocol

Step 1: FORMULATE

Convert the research question into 2-4 specific search queries:

• Official docs query (e.g., "express.js middleware error handling docs")
• Community/GitHub query (e.g., "express error middleware best practices site:github.com")
• Technical blog/comparison query (e.g., "express vs fastify error handling 2025")
• Release notes query if version-specific (e.g., "express 5.x changelog breaking changes")

State the question clearly in one sentence before searching.

Step 2: SEARCH

Execute searches and read actual content (not just snippets):

• Evaluate source credibility: official docs > GitHub repos with stars > recent blog posts > forum answers
• Stop at 3-6 credible sources (not exhaustive — focused)
• If a source contradicts another, note the disagreement

Step 3: EXTRACT

For each finding, record:

• What: The specific fact, recommendation, or pattern discovered
• Source: URL or reference
• Relevance: How this applies to the original question (one sentence)
• Confidence: high (official docs, verified), medium (community consensus), low (single source, opinion)
• Action: What the codebase should do with this information (or "informational only")

Step 4: WRITE

Write findings to .citadel/research/{topic-slug}.md:

# Research: {Topic}

> Question: {The original question}
> Date: {ISO date}
> Confidence: {overall: high/medium/low}

## Findings

### 1. {Finding title}
**What:** {description}
**Source:** {URL}
**Confidence:** {high/medium/low}
**Action:** {recommendation or "informational"}

### 2. {Finding title}
...

## Summary
{2-3 sentences: what was learned, what the recommendation is}

## Open Questions
{Anything that couldn't be resolved — needs human judgment or deeper investigation}

Step 5: RETURN

Return the summary and recommendation to the caller. The research document persists for future reference.

What Research Does NOT Do

• Make architectural decisions (that's the caller's job)
• Install packages or modify code
• Search exhaustively (2-4 queries, 3-6 sources, done)
• Evaluate subjective opinions as facts
• Recommend without evidence

Quality Gates

• Every finding must have a source URL
• Confidence levels must be justified (not guessed)
• Summary must answer the original question or state why it can't be answered
• Research document must be written before returning findings

Exit Protocol

Output findings summary, then:

---HANDOFF---
- Research: {topic}
- Findings: {count} sources analyzed
- Recommendation: {one-line summary}
- Document: .citadel/research/{slug}.md
---