edercnj/x-review-database

Skill: Database Specialist Review

Purpose

Review code changes for database best practices by dynamically loading versioned patterns.md for the detected database engine and version. The checklist and scoring thresholds are derived entirely from those pattern files — no hardcoded criteria.

Activation Condition

Include this skill when database != "none" in the project configuration.

When to Use

• Pre-PR quality validation for database changes
• Reviewing migration scripts
• Checking query performance patterns
• Validating transaction boundaries

Triggers

• /x-review-database 42 — review PR #42 for database patterns
• /x-review-database src/main/resources/db/migration/ — review migration files
• /x-review-database — review all current database changes

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | target | String | No | (current changes) | PR number or file paths to review |

Phase 0.1 — Load Agent Context

Resolve agent name: use --agent runtime flag if provided; otherwise default to database-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 database engine name and version from the ## Technology Versions table.

Step 0b — Map DB engine + version to pattern directory:

| Detected DB | Version | DB Type | Pattern directory | |-------------|---------|---------|-------------------| | PostgreSQL | 16 | sql | src/patterns/backend/data/sql/postgres/16/ | | PostgreSQL | 14 | sql | src/patterns/backend/data/sql/postgres/14/ | | AWS RDS PostgreSQL | 16 | sql | src/patterns/backend/data/sql/aws-rds-postgres/16/ | | AWS Aurora PostgreSQL | 16 | sql | src/patterns/backend/data/sql/aws-aurora/16/ | | AWS RDS Oracle | 19c | sql | src/patterns/backend/data/sql/aws-rds-oracle/19c/ | | Oracle | 19c | sql | src/patterns/backend/data/sql/oracle/19c/ | | H2 | 2.x | sql | src/patterns/backend/data/sql/h2/2.x/ | | MongoDB | 7 | nosql | src/patterns/backend/data/nosql/mongodb/7/ | | MongoDB | 6 | nosql | src/patterns/backend/data/nosql/mongodb/6/ | | DynamoDB | 2024 | nosql | src/patterns/backend/data/nosql/dynamodb/2024/ | | Not detected | latest | sql | src/patterns/backend/data/sql/postgres/16/ (fallback) |

Step 0c — Load pattern files:

DB_PATTERNS="src/patterns/backend/data/${DB_TYPE}/${DB_ENGINE}/${DB_VERSION}/patterns.md"
cat "$DB_PATTERNS" 2>/dev/null || echo "WARN: DB patterns.md not found for ${DB_ENGINE} ${DB_VERSION}"

Extract:

• Full GP-NN list with criticality and score values
• Total maximum score: XX pts line (mandatory)
• Full BP-NN list with criticality and penalty values

Step 0d — Calculate thresholds:

MAX_SCORE = sum of all GP-NN point values (or value on "Total maximum score:" line)
GO_THRESHOLD = MAX_SCORE * 0.80
GO_WITH_RESERVATIONS_THRESHOLD = MAX_SCORE * 0.65

Phase 1 — Gather Context

Collect the review target: PR number or file paths 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 database,performance,architecture")

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

Phase 2 — Dispatch to Database Engineer Agent

Agent(
  subagent_type: "database-engineer",
  description: "Dynamic database review for {target} ({DB_ENGINE} {DB_VERSION})",
  prompt: "Review the code changes for database 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 ({DB_ENGINE} {DB_VERSION}) — evaluate GP-NN and BP-NN from the same file:
{FULL CONTENT OF database-engineer/{DB_TYPE}/{DB_ENGINE}/{DB_VERSION}/patterns.md}

## 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: Database
STORY: {target}
DB_ENGINE: {DB_ENGINE}
DB_VERSION: {DB_VERSION}
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 database quality and top priority fixes}
"
)

Report Path

.aikittools/features/feature-XXXX/reviews/review-database-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 database code found | Report INFO: no database code discovered | | Pattern files not found for detected version | Warn and fall back to highest available version | | Total maximum score: line missing | Sum all GP-NN point values from the table | | No migration files found | Note N/A for migration-related good patterns |