research

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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`:

````markdown
# 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
---
```

From special-place-administrator/citadel_codex, MIT.

More from special-place-administrator/citadel_codex