edercnj/x-review-api

Skill: API Specialist Review

Purpose

Review API changes for compliance with integration-specific best practices by dynamically loading patterns.md for detected REST, webhook, and socket interfaces. The checklist and scoring thresholds are derived entirely from those pattern files — no hardcoded criteria.

Activation Condition

Include this skill when the project uses REST, webhook callbacks, or socket-based APIs.

Triggers

• /x-review-api merchants — review API for a specific feature
• /x-review-api /api/v1/transactions — review a specific endpoint path
• /x-review-api — review all API changes

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | endpoint-or-feature | String | No | (all) | Endpoint path or feature name to review |

Phase 0.1 — Load Agent Context

Resolve agent name: use --agent runtime flag if provided; otherwise default to api-engineer (this skill's statically bound agent).

Skill(skill: "x-internal-load-agent-context", args: "--agent {resolved_agent_name}")

Adopt agent_context.persona. Follow agent_context.rules. Read all agent_context.core_knowledge paths before proceeding. If agent_context.status == "error": halt and report agent_context.message.

Workflow

Step 0a — Read architecture plan for Technology Versions:

ARCH_FILE=$(ls .aikittools/features/*/plans/arch-story-*.md 2>/dev/null | head -1)
if [ -n "$ARCH_FILE" ]; then
  grep -A 30 "## Technology Versions" "$ARCH_FILE" | head -40
fi

Extract API protocol/interface signal from the ## Technology Versions table.

Step 0b — Map protocol + style to pattern directory:

| Detected Protocol | Version | Pattern directory | |-------------------|---------|-------------------| | REST / OpenAPI | any | src/patterns/backend/inbound-outbound/inbound/http/rest/ | | Webhook | any | src/patterns/backend/inbound-outbound/inbound/http/webhook/ | | Socket | iso8583 | src/patterns/backend/inbound-outbound/inbound/socket/iso8583/ | | REST (style not detected) | fallback | src/patterns/backend/inbound-outbound/inbound/http/rest/ |

A single project may use multiple API protocols. Load pattern files for each detected protocol and review all of them.

Step 0c — Load pattern files for each detected protocol/interface:

for PROTOCOL in $DETECTED_PROTOCOLS; do
  case "$PROTOCOL" in
    rest)
      API_PATTERNS="src/patterns/backend/inbound-outbound/inbound/http/rest/patterns.md"
      ;;
    webhook)
      API_PATTERNS="src/patterns/backend/inbound-outbound/inbound/http/webhook/patterns.md"
      ;;
    socket|iso8583)
      API_PATTERNS="src/patterns/backend/inbound-outbound/inbound/socket/iso8583/patterns.md"
      ;;
    *)
      echo "WARN: Unsupported API protocol '$PROTOCOL' for this review profile"
      continue
      ;;
  esac
  cat "$API_PATTERNS" 2>/dev/null || echo "WARN: API patterns.md not found for ${PROTOCOL}"
done

Extract:

• Full GP-NN list with criticality and score values
• Total maximum score: XX pts line (mandatory — used for GO/NO-GO threshold)
• Full BP-NN list with criticality and penalty values

Step 0d — Calculate thresholds (per protocol, or combined):

MAX_SCORE = sum of all GP-NN point values across all loaded protocols
GO_THRESHOLD = MAX_SCORE * 0.80
GO_WITH_RESERVATIONS_THRESHOLD = MAX_SCORE * 0.65

Phase 1 — Gather Context

Collect the review target from args. Run:

git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only --cached

Resolve canonical review packs:

Skill(skill: "x-internal-select-context-packs",
      args: "--phase review --capabilities api,security,architecture")

Read all required assets; read recommended only when relevant to changed API scope.

Phase 2 — Dispatch to API Engineer Agent

Agent(
  subagent_type: "api-engineer",
  description: "Dynamic API review for {target} ({DETECTED_PROTOCOLS} {API_VERSION})",
  prompt: "Review the API changes for best practices. Target: {target}.

Run `git diff HEAD~1..HEAD` to get the diff.

## Dynamic Evaluation Criteria

You MUST evaluate the code exclusively against the patterns loaded below.
Do NOT use hardcoded criteria — score only the GP/BP items explicitly listed.

### Patterns ({PROTOCOL} mapped integration style) — evaluate GP-NN and BP-NN from the same file:
{FULL CONTENT OF src/patterns/backend/inbound-outbound/.../patterns.md}

{IF additional protocols detected: include their patterns too}

## Scoring Instructions

1. For each GP-NN item: award the declared points if the pattern is observed; 0 if absent; partial if partially applied.
2. For each BP-NN item: deduct the declared penalty points if the anti-pattern is found.
3. Final score = Σ(GP points awarded) − Σ(BP penalties applied). Floor at 0.
4. Max score = {MAX_SCORE} pts.
5. GO/NO-GO decision:
   - GO: score ≥ {GO_THRESHOLD} pts AND zero CRITICAL bad patterns found
   - GO-WITH-RESERVATIONS: score ≥ {GO_WITH_RESERVATIONS_THRESHOLD} pts AND no CRITICAL bad patterns
   - NO-GO: score < {GO_WITH_RESERVATIONS_THRESHOLD} pts OR any CRITICAL bad pattern found

## Output Format

ENGINEER: API
STORY: {target}
PROTOCOLS: {DETECTED_PROTOCOLS}
SCORE: XX/{MAX_SCORE}
PERCENTAGE: XX%
STATUS: GO | GO-WITH-RESERVATIONS | NO-GO
---
GOOD_PATTERNS_APPLIED:
- [GP-NN] Pattern name (+X pts) | Evidence: {brief concrete observation}
BAD_PATTERNS_FOUND:
- [BP-NN] Anti-pattern name (-X pts) [CRITICALITY] -- file:line -- Fix: {suggestion}
MISSING_PATTERNS_PATTERNS:
- [GP-NN] Pattern name (0 pts) -- What to add: {guidance}
SUMMARY:
{2-3 sentence summary of overall API quality and top priority fixes}
"
)

Report Path

.aikittools/features/feature-XXXX/reviews/review-api-story-XXXX-YYYY.md

Error Handling

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 API endpoints found | Report INFO: no API changes in scope | | Pattern files not found for detected protocol/style | Warn and fall back to REST server profile | | Total maximum score: line missing | Sum all GP-NN point values from the table | | Multiple protocols detected | Load patterns for each; combine MAX_SCORE |