codenamev/ai-software-architect/specialist-review

Specialist Review (orchestrator)

Single-specialist deep-dive review. This skill is an orchestrator — it identifies the right specialist and delegates the review to that specialist's subagent (agents/<id>.md). The deep-perspective work happens in the subagent's isolated context, not in this skill's main thread.

See ADR-013 for the rationale.

Process

1. Parse the request

Extract from the user's request:

• Specialist role (e.g., "Security Specialist", "Performance Expert")
• Target (e.g., "API authentication", "the payments module", "ADR-007")

If either is unclear, ask one focused clarifying question and stop.

2. Resolve the specialist

Read .architecture/members.yml and find the member whose name or title matches the requested role (case-insensitive, allow common abbreviations like "security" → "Security Specialist").

The member's id (e.g., security_specialist) maps to a subagent at agents/<kebab-id>.md (e.g., agents/security-specialist.md). The drift check in CI (generate-subagents --check) guarantees that file exists if the member exists.

If the requested specialist is not in `members.yml`:

The previous version of this skill auto-created new members on the fly. That is no longer supported because .architecture/members.yml is now protected by a PreToolUse hook (see ADR-013 Pragmatic Analysis). Instead:

1. Tell the user: "<Role> is not in your architecture team. To add them: edit .architecture/members.yml (the PreToolUse hook will refuse the write — set CLAUDE_ALLOW_PROTECTED=1 to override), add a member entry following the existing schema, then run node tools/cli.js generate-subagents."
2. Stop. Do not attempt the review until the member exists.

3. Delegate to the subagent

Dispatch a single Agent call:

Agent({
  subagent_type: "<kebab-id>",
  description: "<Role> review of <target>",
  prompt: <see template below>
})

Prompt template for the subagent call:

You are conducting a focused review of: <target>.
 
Apply your perspective (see your subagent file for your specialty,
disciplines, and domains). Do not range outside your specialty —
other specialists will cover their own areas.
 
Produce a review with these sections:
- Executive summary (2-3 sentences, overall assessment)
- Strengths (what is working well within your domain)
- Concerns (with severity: critical / high / medium / low)
  - For each concern: location (file:line), why it matters, concrete fix
- Recommendations (ordered: immediate / short-term / long-term)
- Risks if unaddressed
- Success metrics (how to verify the recommendations land)
 
If the target requires you to read code, configs, or ADRs, do so via
your Read/Grep/Glob tools. Reference exact files and line numbers.
 
Return the review as markdown. Do not write to disk; the orchestrator
will save it.

4. (Optional) Save the review

If the user asked to persist the review (e.g., "save to reviews/" or "create a review document"):

1. Filename format: <specialist-id>-<target-slug>.md (kebab-case, max 100 chars total). Example: security-specialist-api-authentication.md.
2. Apply input sanitization from `../_patterns.md` to the target slug.
3. Wrap the subagent's returned markdown in the review template header (reviewer name, date, target).
4. Write to .architecture/reviews/<filename>.

If the user did not ask to persist, return the review inline.

5. Report

Concise summary back to the user:

<Title> Review Complete: <target>
 
Reviewer: <Name>
Location: <path or "inline">
Assessment: <executive summary first sentence>
 
Key concerns:
1. <highest-severity concern>
2. <next>
3. <next>
 
Counts: <critical>/<high>/<medium>/<low>
 
Suggested next:
- <immediate action from recommendations>
- <follow-up specialist if cross-cutting concern surfaced>

Why this skill is small

The previous version (~200 lines) inlined detailed review-process instructions because Claude was expected to be the specialist mid-conversation. With subagents, the specialist's persona, perspective, and tool scoping live in agents/<id>.md (generated from members.yml). This skill's job is just to route the request and assemble the response.

Specialist-specific guidance (how a Security Specialist thinks vs a Performance Specialist) lives in the subagent files themselves, not duplicated here. The framework principle: one source of truth per concept.

Related skills

Before:

• list-members — see who is available
• architecture-status — check what's already been reviewed

After:

• create-adr — document decisions arising from findings
• architecture-review — fold this finding into a multi-perspective review

Workflow examples:

1. Security review surfaces auth issue → create-adr for the fix → re-review
2. Performance review identifies bottleneck → ADR for caching strategy → implementation
3. Specialist review on one slice → comprehensive architecture-review for the full version cut

References

• ADR-013 — orchestrator pattern rationale
• Specialist perspectives — high-level reference (subagents are the source of truth for runtime behavior)
• Review template — used when the review is persisted
• Common patterns — input sanitization