Magic

---
name: magic
description: Use when the user asks to research, investigate, analyze, find out, explore, examine, audit, or evaluate something — structured multi-source research with consulting, library-doc search, web search, and guided output delivery.
allowed-tools: Read, AskUserQuestion, mcp__context7__resolve-library-id, mcp__context7__query-docs, Bash(kg check), Bash(kg query *), Bash(kg neighbors *), Bash(kg blast *), Edit(./.workspace/shared/research/**), Bash(git commit -m *)
argument-hint: "[topic or research question]"
---

# /magic — Research, Analysis & Consulting

Structured research and consulting workflow. Uses web search, document analysis, and library documentation. Every decision point uses `AskUserQuestion` so the user explicitly drives the process via action-reaction UI.

<HARD-GATE>
Put every consultation, clarification, and decision to the user through AskUserQuestion rather than plain prose, so they see the structured prompt UI. This applies to every gate in this skill.
</HARD-GATE>

## Autonomy — approve the plan, then run

Once the **Phase 0 scope/source/depth answers** are in, **Phase 1–2 execution runs to completion** without extra consultation questions: `Read`, context7 doc queries and `kg query`/`blast`/`neighbors` are pre-approved by this skill, and read-only git never prompts. **Web search and web fetches are not pre-approved** — they go through Claude Code's normal permission prompts (none in auto mode, or once the user approves them), and every query or URL leaves the machine, so keep private or proprietary details out of them. The skill's real side effects — the **Phase 4** save (pre-approved only inside `.workspace/shared/research/`) and `git add`/`git commit` — are already `AskUserQuestion`-gated. The interactive consultation gates (Phase 0 sources/depth, Phase 3 output/persistence, Phase 5 next steps) stay — magic is question-driven by design. Doctrine: [lore/autonomy.md](../../lore/autonomy.md).

## Standalone & pipeline use

`/magic` is a **standalone** skill — run it any time to research, analyze, or consult; no pipeline required, nothing changes about the flow below when used alone.

It also plugs into the SDLC chain without losing context:
- **Feeds the pipeline:** inside a magician workspace (`.workspace/` present), saved research goes to `.workspace/shared/research/<topic>-<date>.md` — a first-class artifact, like specs and plans. Phase 5 hands that **path** (not just a summary) to the next stage, so design/planning/debugging start informed.
- **Fed by the pipeline:** `/conjure`, `/blueprint`, `/unravel`, and `/manifest` read `.workspace/shared/research/` and suggest `/magic` when a decision needs external evidence.
- **Internal sources:** for the user's own Jira tickets/epics/boards or Confluence pages, use the `magician:jira` / `magician:confluence` skills (they use magician's bundled CLIs and walk through setup if not configured) rather than web search. If the user prefers another installed Jira or Confluence integration, use that. Fold what they return into the findings like any other source. **Skip a source the user has opted out of** ([lore/integration-prefs.md](../../lore/integration-prefs.md)) — don't suggest setting it up.
- **The codebase itself:** when the question is about the user's own repo, query the **knowledge graph** first — `kg check` then `kg query "<topic>"` (and `kg neighbors`/`kg blast` for relationships) — and `Read` the ranked `file:line` ranges it returns, instead of broad greps. It's a first-class internal source: cheaper, faster, and shared across agents with no context loss. If there's no index, fall back to grep/Read and offer once to build one (`kg init`, run only on the user's yes) — opt-out aware ([lore/integration-prefs.md](../../lore/integration-prefs.md), key `knowledge-graph`). Details: [knowledge-graph skill](../knowledge-graph/references/retrieval.md).

## When it's suggested

Magician's `UserPromptSubmit` hook may add a note that this skill covers research and analysis when a prompt contains research-intent words (for example **research, investigate, analyze, explore, examine, assess, evaluate, discover, audit, study, survey, probe, benchmark**). The note is a suggestion, not an instruction — use this skill only when the request really is research.

When you start it from such a note, say so before any other action:
> "Starting /magic for structured research. Let me gather a few inputs before diving in."

---

## Phase 0 — Scope & Sources

### Step 0.1 — Understand the goal

Read the user's original message carefully. Silently classify the research into one of these types — this determines which sources and output formats to offer:

| Type | Signals | Notes |
|---|---|---|
| **Academic / scientific** | thesis, diploma, dissertation, paper, study, hypothesis, literature review, citation, journal, research question, scientific, university, course | Target academic databases in web search; offer citation-aware output formats |
| **Software / tech library** | library name, version, API, framework, npm, Maven, pip, compatibility, SDK | context7 may be relevant |
| **Financial / business** | revenue, Q1–Q4, KPI, margins, market share, P&L, report | Read tool for files; structured financial output |
| **Document / file analysis** | file path mentioned, .xlsx/.pdf/.docx, "this report", "this article" | Read tool; context7 NOT relevant |
| **General / strategic** | anything else | Web search; broad output options |

Do NOT ask for anything already clear from the message.

### Step 0.2 — Scope gate: sources + depth (ONE batched AskUserQuestion)

Batch both up-front decisions into a **single** AskUserQuestion call so the user approves scope once — don't drip them as two separate prompts ([lore/autonomy.md](../../lore/autonomy.md): clarify up front, batched). Read [references/questions.md](references/questions.md) → "Phase 0 — Source selection" (pick the variant matching the Step 0.1 classification) **and** "Phase 0 — Research depth", then pass **both** question blocks in the `questions` array of one AskUserQuestion call. Wait for the response before proceeding.

> **Model & effort:** the depth choice maps onto reasoning effort — Quick overview ≈ `/effort low`, Standard depth ≈ `/effort medium`, Deep dive ≈ `/effort high` (for exhaustive sweeps, your model's deepest level — `xhigh`, or `max` on models that lack it). If the session is on an older model than ideal, suggest an upgrade rather than switching silently. See [lore/models.md](../../lore/models.md).

---

## Phase 1 — Tool Availability Check

### Step 1.1 — Check context7

**Only proceed with this step if both conditions are true:**
1. User selected "Tech Library Docs (context7)"
2. The research topic is genuinely about a software library, framework, package, or version compatibility

If the topic is a business document, financial report, article, spreadsheet, or anything that is not a software library/framework — **skip this step entirely** and go to Step 1.2.

If user selected "Tech Library Docs (context7)", check availability: context7 is available when `mcp__context7__resolve-library-id` is in your tool list.

If it isn't, read [references/questions.md](references/questions.md) → "Phase 1 — context7 not installed" and deliver that block via AskUserQuestion. Never add the server yourself: on "Show me the command", print the command for the user to run; either way, continue without context7 and note the limitation in findings.

### Step 1.2 — Document paths (if selected)

If user selected "My Documents / Files", read [references/questions.md](references/questions.md) → "Phase 1 — Document source" and deliver that block via AskUserQuestion. Wait for file paths if the user chose to type them; extract paths from the next message. Reading local documents uses the built-in Read tool — no external service required.

---

## Phase 2 — Research Execution

Execute research in parallel where possible. Take structured notes as you go.

### Step 2.1 — Web Search (if selected)

Use WebSearch with 2–4 targeted queries (each search prompts unless the user already approved web search or runs in auto mode). Build queries from the public topic only — never paste private file contents, credentials, or internal names into a query. Tailor queries to the research type:

**Academic/scientific topic** — prefix queries to target academic sources:
- `site:scholar.google.com <topic>` or `"<topic>" filetype:pdf journal`
- `arXiv <topic>` for STEM/CS/physics/math
- `PubMed <topic>` for biomedical/life sciences
- `IEEE "<topic>"` for engineering/electronics
- `ACM "<topic>"` for computer science
- Include the research question as a direct search query too

**General/business topic** — standard targeted queries:
- Use specific terms, dates, and named entities
- Include news sources, industry reports, official publications

For each query:
1. Formulate the query (academic-targeted or general as above)
2. Call WebSearch tool
3. Extract key facts, quotes, and sources — **note author, title, year, URL** for every source (essential for citations in academic work)
4. Assess source credibility: peer-reviewed > institutional > reputable press > general web

Synthesize web findings into a running outline.

### Step 2.2 — Tech Library Docs via context7 (if selected and topic is software/tech)

For each library or framework relevant to the topic (context7 queries go to the context7 service, so use the public library name and a generic question — never private code or internal names):
1. Resolve the library ID: call `mcp__context7__resolve-library-id` with the library name
2. Query the docs: call `mcp__context7__query-docs` with the resolved ID and a focused query
3. Extract relevant sections and cross-reference with other findings

**Only use this step for genuine software library/framework questions** — e.g. "what Spring Boot version supports Java 21?", "what's the correct Axios API for interceptors?". Do NOT invoke context7 for business reports, financial documents, articles, or any non-library topic.

### Step 2.3 — Document / File Analysis (if selected)

Uses the **Read tool** — no external service. For each provided file path:
1. Call the Read tool on the file path
2. For **financial documents** (reports, P&L, balance sheets): extract key metrics, dates, figures, YoY comparisons, notable trends, risks, executive summary
3. For **spreadsheets / data files** (.xlsx, .csv): extract headers, key rows, totals, trends, anomalies
4. For **articles / research papers**: extract thesis, main arguments, evidence, conclusions, citations
5. For **technical documents** (architecture docs, RFCs, specs): extract decisions, constraints, APIs, versions, dependencies
6. For **general business documents** (reports, memos, meeting notes): extract main points, action items, decisions made

### Step 2.4 — Synthesis

Cross-reference all findings. Identify:
- Consensus points (multiple sources agree)
- Contradictions or gaps
- Key numbers, dates, or facts
- Actionable insights or recommendations

---

## Phase 3 — Output Format Consultation

### Step 3.1 — Choose output format (AskUserQuestion)

Read [references/questions.md](references/questions.md) → "Phase 3 — Output format". Pick the academic or all-other-topics variant (and the citation-style follow-up when an academic format is chosen) and deliver it via AskUserQuestion. If the user selects "Visual design via /conjure", invoke `/conjure` with the topic and findings outline, then return here.

### Step 3.2 — Persistence decision (AskUserQuestion)

Read [references/questions.md](references/questions.md) → "Phase 3 — Persistence decision" and deliver that block via AskUserQuestion. If saving: determine an appropriate filename from the topic. **Inside a magician workspace (`.workspace/` exists), default to `.workspace/shared/research/<topic>-<date>.md`** (creating the dir if needed) so the findings become a pipeline artifact; otherwise save to the cwd or a path the user gives.

---

## Phase 4 — Deliver & Persist

### Step 4.1 — Present findings

Write the findings in the format chosen in Phase 3. Include:
- Source attribution for web content
- File references for local documents
- Clear headings and structure
- A summary/conclusion section

For findings the user wants to circulate, you can publish them as a Claude Code **Artifact** (a live page on claude.ai, team-co-editable on Team/Enterprise) — offer it, don't create it unprompted. Publishing to a **public** link (anyone with the URL can view it) is an outward sharing action: **confirm it, keep it account-private by default, and never expose proprietary/internal data, secrets, or confidential source material to a public link.**

### Step 4.2 — Save to file (if requested)

Write findings to the agreed filename with the Write tool. Saving inside `.workspace/shared/research/` is pre-approved by this skill; any other path goes through the normal permission prompt.

### Step 4.3 — Commit (if requested)

Read [references/questions.md](references/questions.md) → "Phase 4 — Commit message", deliver that block via AskUserQuestion, then run the `git add`/`git commit` it specifies with the confirmed message.

---

## Phase 5 — Navigate & Suggest

### Step 5.1 — Assess the research silently

Before asking anything, look at what was just researched and classify it:

| Research type | Signals | Best next skills |
|---|---|---|
| Academic / scientific | thesis, paper, literature review, citation, study, diploma | /conjure (research poster or slides), /magic again (next research angle) |
| Financial / business | revenue, Q1–Q4, KPIs, margins, market share | /conjure (dashboard), /blueprint (action plan) |
| Technical feature / API | endpoints, SDK, library, integration | /blueprint (plan), /conjure (design), /ward (implement) |
| Existing feature to port/change | usage of a live app, vendor/3rd-party, "recreate/clone", "swap the provider", migration | /transmute (comprehend → port or integrate), /blueprint |
| Bug / incident | error, failure, crash, regression, issue | /unravel (debug), /sentinel (security angle) |
| Security / vulnerability | CVE, injection, auth, permissions, exposure | /sentinel (full scan) |
| Performance / scalability | latency, throughput, memory, profiling | /accelerate (profile) |
| Architecture / system design | components, services, data flow, schema | /conjure (visual spec), /blueprint (plan) |
| General knowledge / comparison | options, alternatives, pros/cons, landscape | /conjure (visual comparison), /magic again |

Select the 2 most contextually relevant skills. Always include "Dig deeper" and "Done" as the last two options.

### Step 5.2 — Propose next steps (AskUserQuestion)

Read [references/next-steps.md](references/next-steps.md). Pick the template matching the research type, adapt the question text to reflect what was actually found (not generic), and deliver it via AskUserQuestion.

### Step 5.3 — Act on selection

When handing off, pass the **saved research artifact path** (if saved, e.g. `.workspace/shared/research/<topic>-<date>.md`) plus a 2–3 sentence summary, so the next stage reads the full findings with zero context loss (see [lore/subagent-context.md](../../lore/subagent-context.md)).

| Selection | Action |
|---|---|
| /conjure | Invoke `/conjure` — pass the research artifact path + topic + a 2–3 sentence summary so design starts informed |
| /blueprint | Invoke `/blueprint` — pass the research artifact path as spec/requirements input |
| /unravel | Invoke `/unravel` — pass the identified bug/incident and the research artifact path as the starting point |
| /sentinel | Invoke `/sentinel` — no extra context needed, it scans the codebase |
| /accelerate | Invoke `/accelerate` — pass performance concerns from findings (and the artifact path) as focus areas |
| /transmute | Invoke `/transmute` — when the research comprehended an existing feature to port elsewhere or change in place; pass the research artifact path as the seed for the dossier |
| Dig deeper | Use AskUserQuestion to ask which area, then return to Phase 2 with a focused query |
| Done | Go to Step 5.4 |

### Step 5.4 — Graceful exit

When the user selects "Done", close with:

1. One sentence summarising what was accomplished (topic + output location if saved)
2. A warm sign-off that reflects the work done, e.g.:

> "That's a solid research session on [topic] — findings saved to [file] if you need them later. Have a great day!"

or if nothing was saved:

> "Good investigation on [topic]. Hope the findings give you what you needed — have a great day!"

Keep it brief. No bullet lists. No meta-commentary. Just a clean, friendly close.

## Obstacles

If this skill runs as a dispatched unit (under /orchestrate, /weave, /manifest, /transmute, or another skill) and hits something that blocks or degrades the work, do not wait for a human who is not there and do not silently ship a degraded result — return an Obstacles block to the caller, alongside whatever you did complete:

```
STATUS: BLOCKED | DEGRADED | NEEDS_CONTEXT
OBSTACLE: <one-line label of what blocked or degraded the task — the claim alone>
BLOCKER: <the specific, actionable cause — distilled, never a raw traceback or dumped log>
SEVERITY: Critical | High | Medium | Low
WORKAROUND: <what you did to proceed and what it leaves unverified; empty if still fully blocked>
RECURRENCE: First-seen | Recurring | Systemic
SCOPE: <this task only | likely hits sibling/downstream work too>
NEXT: <the action or decision the caller must make to clear it — retry with X, supply input Y, accept degraded, or escalate>
```

When invoked interactively by a human, surface the same obstacle in prose instead. Omit the block entirely on a clean run. See [lore/obstacles.md](../../lore/obstacles.md).

## Completion Signal

"Magic complete. Researched <topic> across <N> sources. Findings <saved to .workspace/shared/research/… | delivered above>. Suggested next: <skill>."