edercnj/x-review-specialist

Skill: x-review-specialist — Specialist Review Orchestrator

Purpose

Orchestrate all applicable specialist review skills dynamically based on the project's active technology context. Invokes each specialist skill individually and in parallel. Security (/x-review-security) and QA (/x-review-qa) are always mandatory regardless of tech context.

Triggers

• /x-review-specialist — review current branch
• /x-review-specialist STORY-ID — review specific story
• /x-review-specialist --scope security,qa — run only specific specialists
• /x-review-specialist --no-auto-fix-story — disable auto-generation of correction story

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | STORY-ID | No | Story to review (pattern: story-XXXX-YYYY). Defaults to current-branch detection. | | --scope <list> | No | Comma-separated specialist list. Filters against Specialist Table. Security+QA always included. | | --no-auto-fix-story | No | Disable automatic correction-story generation; fall back to AskUserQuestion. | | --interactive | No | Set interactiveMode=interactive on execution-state.json (Rule 20). | | --task-exit-gate | No | Task-level exit gate mode: scoped to expects-reviews from the task file; no dashboard; no correction story. | | --task-id <TASK-ID> | No | When --task-exit-gate, the task being gated. Used to read expects-reviews from task-TASK-*.md and write exit gate report. |

Output Contract

| Artifact | Path | Produced By | |----------|------|-------------| | Per-specialist report | .aikittools/features/feature-XXXX/reviews/review-{specialist}-story-XXXX-YYYY.md | Phase 2 (Write per specialist) | | Consolidated dashboard | .aikittools/features/feature-XXXX/reviews/dashboard-story-XXXX-YYYY.md | Phase 3 (cumulative — RULE-006) | | Remediation tracker | .aikittools/features/feature-XXXX/reviews/remediation-story-XXXX-YYYY.md | Phase 3 | | Threat-model update | results/security/threat-model.md | Phase 3 (incremental, STRIDE) | | Correction story (opt.) | .aikittools/features/feature-XXXX/reviews/correction-story-XXXX-YYYY.md | Phase 4 (conditional) | | Frontmatter artifact | .aikittools/features/feature-XXXX/reviews/review-story-XXXX-YYYY.md | Phase 5 (MANDATORY — Rule 24 §Camada-1) | | Exit gate report (opt.) | .aikittools/features/feature-XXXX/reviews/exit-gate-TASK-XXXX-YYYY-NNN.md | Phase 5 (only when --task-exit-gate) |

Task exit gate mode (--task-exit-gate):

When --task-exit-gate is active:

• Read expects-reviews from task-TASK-*.md frontmatter; use as --scope (do NOT force-add Security+QA)
• Skip Phase 3 dashboard generation (no cumulative dashboard update)
• Skip Phase 4 correction-story generation
• Write exit gate report to .aikittools/.../reviews/exit-gate-{TASK_ID}.md with verdict and specialist findings
• Return decision: GO, GO-WITH-RESERVATIONS, or NO-GO to caller (x-implement-task Phase 3.7)

Specialist Table — Dynamic Selection

Max Score is fully dynamic: each specialist skill reads its own versioned patterns.md files and computes the total maximum score from GP-NN point sums. The orchestrator also reads scoring_summary from x-internal-select-context-packs (Layer D) to obtain aggregated thresholds. Values below are reference estimates only; actual maximums depend on detected version and frontmatter.

| Specialist | Skill Invoked | Est. Max Score | Condition | |------------|---------------|----------------|-----------| | Security | /x-review-security | /30 | ALWAYS — mandatory | | QA | /x-review-qa | /36 | ALWAYS — mandatory | | Performance | /x-review-performance | /26 | performance != none | | Database | /x-review-database | dynamic | database != none | | Observability | /x-review-observability | /18 | observability != none | | DevOps | /x-review-devops | /20 | container != none (Docker/K8s/Helm/Terraform) | | API | /x-review-api | dynamic | REST/GraphQL/gRPC interface present | | Events | /x-review-events | /28 | Event-driven / message broker (Kafka, RabbitMQ, etc.) | | Data Modeling | /x-review-data-modeling | /20 | database != none AND architecture is Hexagonal/DDD/CQRS | | Compliance | /x-review-compliance | /24 | Compliance frameworks active (PCI-DSS, LGPD, GDPR, HIPAA, SOX) |

Each individual skill loads its own versioned pattern files for the current project and calculates score dynamically. This orchestrator does NOT duplicate domain checklists — it delegates entirely.

Dynamic Scoring Configuration

Scoring thresholds (GO/NO-GO) are loaded dynamically from scoring_summary returned by x-internal-select-context-packs Layer D.

Fallback thresholds (used when scoring_summary is absent)

| Verdict | Condition | |---|---| | GO | achieved score ≥ 80% of max AND zero CRITICAL bad patterns | | GO-WITH-RESERVATIONS | achieved score ≥ 65% AND no CRITICAL bad patterns | | NO-GO | achieved score < 65% OR any CRITICAL bad pattern |

Dynamic threshold resolution (Phase 1)

1. Read scoring_summary from x-internal-select-context-packs output.

2. IF scoring_summary is present AND scoring_summary.total_max_positive_score > 0:
   - AGGREGATE_MAX_POSITIVE = scoring_summary.total_max_positive_score
   - GO_THRESHOLD_PCT = scoring_summary.go_nogo_threshold_pct      (default: 80)
   - RESERVATIONS_PCT = scoring_summary.go_with_reservations_pct   (default: 65)
   - LOG: "[INFO] Using dynamic scoring config from asset frontmatter."

3. ELSE:
   - Use fallback thresholds above.
   - LOG: "[WARN] scoring_summary not available. Using default GO/NO-GO thresholds."

4. Pass GO_THRESHOLD_PCT and RESERVATIONS_PCT to Phase 3 consolidation.

Canonical Technology Selection

Skill(skill: "x-internal-select-context-packs",
      args: "--phase review --capabilities security,qa,performance,database,observability,devops,api,events,data-modeling,compliance")

Store the full output including scoring_summary and arch_questions_by_category for use in Phases 1 and 3.

Workflow Overview

Phase 0: PRE-CHECK     → Idempotency check (skip if reports fresh)
Phase 1: DETECT        → Identify branch/diff + active specialists via tech-context
Phase 2: REVIEW        → Invoke all active specialist skills in parallel (SINGLE Batch message)
Phase 3: CONSOLIDATE   → Score, dashboard, remediation tracker, STRIDE threat model
Phase 4: STORY         → Generate correction story if CRITICAL/HIGH/MEDIUM findings
Phase 5: FRONTMATTER   → Emit YAML frontmatter (Rule 24 — mandatory)

Phases 0–5

• Phase 0 — Idempotency Pre-Check: extract story ID, derive feature dir, check report mtime vs git log -1 --format=%ct HEAD; on freshness, skip to Phase 3 (dashboard regeneration); persist interactiveMode to execution-state.json.

• Phase 1 — Detect Context: extract story ID; run git diff main --stat; abort on no changes; resolve active specialists via x-internal-evaluate-tech-context + x-internal-select-context-packs; apply Specialist Table conditions (always include Security + QA; filter others by tech-context); apply --scope override if provided.

  Technology Versions (primary source for specialist pattern selection):

  ARCH_FILE=$(ls .aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md 2>/dev/null | head -1)
  grep -A 30 "## Technology Versions" "$ARCH_FILE" 2>/dev/null | head -40
  

  Store the resulting version map as TECH_VERSIONS. Pass it to each specialist skill invocation in Phase 2 so specialists can select the correct versioned pattern directories. If arch file not found, fall back to techProfile.versions from x-internal-evaluate-tech-context.

  Application Patterns detection (MANDATORY — always after tech context):

  APP_PATTERNS_FILE="docs/architecture/application-patterns.md"
  HAS_APP_PATTERNS=false
  APP_PATTERNS_CONTEXT=""
  if [ -f "$APP_PATTERNS_FILE" ]; then
    HAS_APP_PATTERNS=true
    APP_PATTERNS_CONTEXT=$(cat "$APP_PATTERNS_FILE")
    LOG "[INFO] application-patterns.md found — will cross-check {N} patterns during specialist reviews."
  else
    LOG "[INFO] application-patterns.md not found — skipping pattern cross-check (not blocking)."
  fi
  

  Store HAS_APP_PATTERNS and APP_PATTERNS_CONTEXT for use in Phase 2.

• Phase 2 — Parallel Reviews: CONTEXT ISOLATION (specialists receive metadata only); PRE gate (Rule 25 Invariant 4); emit a SINGLE assistant message bundling all TaskCreate + all Skill(x-review-*) calls for ACTIVE specialists only; then sibling TaskUpdate calls (Batch B); wave POST gate (Batch C). When --agent <name> provided, append --agent <name> to every Skill(x-review-*) call so each specialist adopts the bound persona.

  Application Patterns cross-check (inject when HAS_APP_PATTERNS=true): When invoking each specialist skill, append the following instruction to its context prompt:

  ## Application Patterns — Cross-Check Required
  
  The project has declared the following active patterns in `docs/architecture/application-patterns.md`.
  As part of your review, you MUST cross-check the implementation against EVERY pattern listed below.
  For each pattern, assess: (a) Is the pattern followed? (b) Is it violated? (c) Is it not applicable for this story?
  Report findings in a "## Pattern Breaks" section in your specialist report.
  
  {APP_PATTERNS_CONTEXT}
  

  Specialists MUST include a ## Pattern Breaks section in their report even if all patterns are compliant (use: "No pattern breaks detected."). This section is consumed by x-review-tech-lead Phase 3 for the Pattern Coverage rubric.

• Phase 3 — Consolidation: 3a Collect & Score all specialist reports; 3b Issue Summary by severity (CRITICAL/HIGH/MEDIUM/LOW); 3c Save per-specialist reports via Write; 3d Update cumulative dashboard (RULE-006); 3e Build/update remediation tracker (Open items from FAILED/PARTIAL); 3f STRIDE threat-model update for security findings; 3g Console summary box.

• Phase 4 — Correction Story: only when CRITICAL/HIGH/MEDIUM findings exist; auto-generate by default (pause for AskUserQuestion only on CRITICAL Security findings or --no-auto-fix-story); save to correction-story-XXXX-YYYY.md.

• Phase 5 — Emit Frontmatter: pre-gate, assemble body, prepend YAML frontmatter conforming to schema (schema-version: "1.0", generated-by: x-review-specialist@<sha>, decision: NO-GO/GO-WITH-RESERVATIONS/GO); validate via audit-review-frontmatter.sh; post-gate. Absent frontmatter aborts with REVIEW_FRONTMATTER_INVALID — no fallback (Rule 24 §Camada-1).

Error Envelope

Convenções de erro/degradação transversais a review/audit (empty input, RULE-012 template fallback, falha de specialist, build/test override, idempotência) vivem em _shared/error-handling-review.md. As linhas abaixo são específicas desta skill.

| Scenario | Action | |----------|--------| | No changes found relative to main | Abort: No changes found relative to main. | | Specialist skill returns invalid output | Mark specialist as FAILED, score 0, continue | | Dashboard template not found | Log warning, skip dashboard, continue | | All specialists return FAILED | Overall status REJECTED, report saved with 0 scores | | Phase 5 frontmatter audit exit ≠ 0 | Abort with REVIEW_FRONTMATTER_INVALID (Rule 24) | | PRE gate fails | Exit 12; resolve stale execution-state.json before retry |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-review-specialist | alias | Deprecated; forwards to this skill | | x-review-pr | called-by | x-review-pr Phase 1 invokes this skill | | x-review-tech-lead | followed-by | x-review-pr calls x-review-tech-lead after this skill | | x-review-security | calls | Always activated | | x-review-qa | calls | Always activated | | x-review-performance | calls | Conditional: performance active | | x-review-database | calls | Conditional: database active | | x-review-observability | calls | Conditional: observability active | | x-review-devops | calls | Conditional: container active | | x-review-api | calls | Conditional: REST/GraphQL/gRPC | | x-review-events | calls | Conditional: event-driven | | x-review-data-modeling | calls | Conditional: DB + Hexagonal/DDD/CQRS | | x-review-compliance | calls | Conditional: compliance frameworks | | x-internal-evaluate-tech-context | calls | Determine active specialists | | x-internal-select-context-packs | calls | Resolve review knowledge packs | | x-internal-verify-phase-gates | calls | Rule 25 Invariant 4 gate enforcement | | audit-review-frontmatter.sh | calls (Phase 5) | Mandatory frontmatter validation |