| 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.
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
