Expert Analysis

---
name: expert-analysis
description: Dispatches `forge-expert` subagents in parallel — one per chosen domain — to produce focused analyses of a feature against the codebase before a plan is drafted. Each expert covers one domain (architecture, performance, data/state, UI/UX, security, testing, build/tooling — pick from the role catalog) and returns a structured report citing `file:line` evidence. Use as Step 3 of the forge workflow, after the user has stated the feature and the orchestrator has gathered baseline codebase context. Do NOT auto-fire; always orchestrator-triggered to keep the workflow sequence intact.
user-invocable: false
color: yellow
---

# Expert Analysis Dispatch

Dispatch N domain experts in parallel via the `forge-expert` subagent. The agent's system prompt owns the role archetype, citation discipline, return format, and read-only constraints — this skill provides the per-dispatch parameters and orchestrates the parallel call.

## Required Inputs

- The feature requirements as the user expressed them (verbatim, not paraphrased).
- A short orchestrator summary of the codebase area the feature touches (≤ 10 bullet points or file paths).
- 3–5 anchor files (`path` or `path:line`) the experts should start from. Experts walk the code themselves; the anchor list seeds, it does not bound.
- The list of domains to cover, picked from `references/expert-roles.md`.

## Picking experts

Use as many experts as the feature genuinely needs, capped at **5**. The selection is driven by the Step-2 search — every distinct architectural concern surfaced by the search becomes one expert dispatch.

- **Cap: 5 experts.** Past 5, reports start to repeat each other and `/forge:master-plan` spends its budget reconciling overlap.
- **Merge near-duplicates.** If two domains' analyses would overlap by > 50% (e.g. both reasoning about the same dialog state machine), dispatch one combined expert with both lenses in the role line, not two separate experts.
- **Honor explicit user picks.** If the user names domains ("get a security review and a performance review"), dispatch exactly that list and skip the heuristic.

There is no hard floor and no narrow-feature gate. A focused single-expert dispatch is occasionally the right call (e.g. a pure performance question). The cap is the only structural constraint.

## Dispatch Template

MUST invoke `Agent` once per chosen domain, all calls in a single tool-use block so they run in parallel. For each dispatch:

```
Agent(
  description: "<Domain>: analyze <feature> against codebase",
  name: "<Domain> expert",
  subagent_type: "forge-expert",
  run_in_background: false,
  prompt: """
## Domain
<one of: architecture, performance, data-state, ui-ux, security, testing, build-tooling>

## Stack experience
<one-line addendum from references/expert-roles.md "Stack-specific role tuning" — leave empty if stack unknown>

## Feature
<verbatim feature requirements from user>

## Anchor files
- `path/to/anchor1.ext` — <one phrase: why this anchor>
- `path/to/anchor2.ext:42` — <…>
- ...

## Domain authority (omit section if no project skill was loaded in Step 2.3)
<paste the full output of any project skill invoked in Step 2.3 that is relevant to this expert's domain>
<a schema skill's output here means the expert should not re-derive field names or types from file searches — treat this output as authoritative>
"""
)
```

The `forge-expert` agent's system prompt (in `forge/agents/forge-expert.md`) carries the role archetype, return format, citation discipline, and read-only constraints. The dispatch prompt only inlines the four sections above.

For the role catalog (which domains apply to which features, stack-specific tuning), see [references/expert-roles.md](references/expert-roles.md).

## Critical Constraints

- **Parallel, not sequential.** All `Agent` calls go in a single tool-use block. Sequential dispatch wastes wall-time and breaks the workflow timing assumptions of `/forge:master-plan`.
- **`subagent_type: "forge-expert"` on every dispatch.** The agent definition handles model, `maxTurns`, tools, and the canonical role / return-format / constraints.
- **Cap at 5.** This is the only quantity gate. No floor, no narrow-feature gate; let the Step-2 search drive the count.
- **Anchor, don't dump.** Inline 3–5 anchor files with one-phrase reasons, not a long context summary. The `file:line` citation discipline is what produces grounded output; prefatory context dumps just inflate the prompt.
- **Keep prompts self-contained.** The expert receives only what's in the `prompt` field; it cannot see the orchestrator's prior conversation. Inline the feature text and the anchor list verbatim.

## Next Step

After all experts return, invoke `/forge:master-plan` to synthesize their reports into a single implementation plan.

## Additional resources

- For the catalog of expert domains, role-pick guidance, and stack-specific role addenda, see [references/expert-roles.md](references/expert-roles.md)