edercnj/x-review-tech-lead

Skill: x-review-tech-lead — Tech Lead Review with Dynamic Dimensions

Purpose

Perform the final holistic Tech Lead review, issuing a GO or NO-GO decision. Unlike a fixed rubric, the review dimensions are dynamically derived from:

1. The project's active technology context (tech-context.config.json)
2. The architecture plan generated for this story (arch-story-XXXX-YYYY.md)
3. All specialist reports produced by x-review-specialist
4. All developer reports produced by x-review-developer

The Tech Lead verifies that:

• Every dimension called for by the architecture plan was reviewed
• No specialist dimension is missing coverage
• Security (always mandatory) is addressed with at least basic protections
• Test coverage meets absolute gates (>= 95% line / >= 90% branch)
• All specialist and developer verdicts are considered in the final decision

Triggers

• /x-review-tech-lead — review current branch
• /x-review-tech-lead STORY-ID — review specific story
• /x-review-tech-lead NNN — review PR #NNN
• /x-review-tech-lead --skip-reports-check — skip validation of whether specialist/developer reports exist

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | Positional | No | story-XXXX-YYYY, PR-NNN, or current branch | | --interactive | No | Enable interactive gate (AskUserQuestion) on NO-GO | | --skip-reports-check | No | Do not warn on missing specialist/developer reports |

Output Contract

| Artifact | Path | |----------|------| | Tech Lead report | .aikittools/features/feature-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md | | Updated dashboard | .aikittools/features/feature-XXXX/reviews/dashboard-story-XXXX-YYYY.md | | Updated remediation tracker | .aikittools/features/feature-XXXX/reviews/remediation-story-XXXX-YYYY.md | | Frontmatter on Tech Lead report | YAML block (MANDATORY — Rule 24 §Camada-1) |

Workflow Overview

Phase 0: CONTEXT      → Idempotency + detect story/PR + load arch plan + tech context
Phase 1: LOAD REPORTS → Read all specialist and developer reports from reviews/
Phase 2: AUDIT        → Identify missing dimensions + unreported specialist gaps
Phase 3: REVIEW       → Execute dynamic rubric (base + conditional per tech-context)
Phase 4: VERDICT      → Compile GO/NO-GO; update dashboard + remediation tracker
Phase 5: FRONTMATTER  → Emit YAML frontmatter (MANDATORY — Rule 24 §Camada-1)

Phase 0 — Context Loading

0.1 — Load Agent Context

Resolve agent name: use --agent runtime flag if provided; otherwise default to tech-lead (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. If agent_context.status == "error": halt and report agent_context.message.

0a — Idempotency

Check if review-tech-lead-story-XXXX-YYYY.md exists and mtime(report) >= mtime(latest commit). If fresh, skip to Phase 4 (dashboard update only).

0b — Detect Story/PR

# If PR number provided:
gh pr view {PR} --json headRefName,title --jq '{branch: .headRefName, title: .title}'
# Extract story ID from branch

0c — Load Architecture Plan

# Find arch plan for this story
ls .aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md 2>/dev/null

Read the architecture plan if it exists. Extract:

• Declared components and their responsibilities
• Active NFRs (Security, Performance, Observability, Scalability, etc.)
• Technology decisions section (which tech capabilities were activated)
• Identified dependencies and integration points
• ## Technology Versions section (primary source for versioned pattern selection)

If no arch plan exists: log INFO: Architecture plan not found — using tech-context.config.json for dimension derivation.

From ## Technology Versions table, extract:

• Language + version (e.g., java: 21)
• Framework + version (e.g., springBoot: 3.x)
• Database + version (e.g., postgres: 14)
• API protocol + version (e.g., rest: openapi-3.1)

This version map is passed to Phase 3 so the dynamic rubric can cross-check that specialist reports used the correct versioned patterns.

0d — Load Tech Context

Skill(skill: "x-internal-evaluate-tech-context",
      args: "--phase review --capabilities java,kotlin,typescript,angular,react,swift,security,qa,performance,database,observability,devops,api,events,data-modeling,compliance")

Produce activeDimensions[]: the set of dimensions this project requires to be reviewed.

If techProfile.versions is not all-null, prefer arch file ## Technology Versions over techProfile.versions as the authoritative source (arch file is intentional; tech-context is auto-detected).

0e — Load Application Patterns (conditional)

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 loaded — {N} patterns to cross-check in Phase 3."
else
  LOG "[INFO] application-patterns.md not found — Pattern Coverage section will be omitted from report."
fi

Store HAS_APP_PATTERNS and APP_PATTERNS_CONTEXT for use in Phase 3.

Phase 1 — Load Specialist and Developer Reports

Read all reports from .aikittools/features/feature-XXXX/reviews/:

ls .aikittools/features/feature-XXXX/reviews/review-*-story-XXXX-YYYY.md 2>/dev/null

Parse each report for:

• ENGINEER / reporter name
• SCORE and max score
• STATUS (Approved/Rejected/Partial)
• FAILED and PARTIAL items with severity

Phase 2 — Dimension Audit

Cross-reference activeDimensions[] against reports loaded in Phase 1:

| Active Dimension | Expected Report Pattern | Missing = Dimension Gap | |-----------------|------------------------|------------------------| | security | review-security-* | CRITICAL gap | | qa | review-qa-* | CRITICAL gap | | database | review-database-* | HIGH gap | | observability | review-observability-* | MEDIUM gap | | devops | review-devops-* | MEDIUM gap | | api | review-api-* | HIGH gap | | events | review-events-* | MEDIUM gap | | performance | review-performance-* | MEDIUM gap | | compliance | review-compliance-* | HIGH gap | | java | review-developer-java-* | MEDIUM gap | | kotlin | review-developer-kotlin-* | MEDIUM gap | | (other langs) | review-developer-{lang}-* | MEDIUM gap |

Security dimension is ALWAYS in activeDimensions — missing security report is always CRITICAL.

Each CRITICAL dimension gap is an automatic NO-GO trigger.

Phase 3 — Dynamic Rubric Execution

Base Rubric (Always — 30 Points)

| Section | Points | Checks | |---------|--------|--------| | A. Code Hygiene | 4 | Unused imports, dead code, warnings | | B. Naming | 4 | Intention-revealing, no disinformation | | C. Functions | 4 | SRP, size limits, max params | | D. Design | 4 | Law of Demeter, CQS, DRY | | E. Error Handling | 4 | Rich exceptions, no null returns, no generic catch | | F. Architecture | 6 | Layer boundaries, SRP, DIP, follows arch plan | | G. Tests & Coverage | 4 | ALL tests pass, line >= 95%, branch >= 90% | | H. Security Baseline | 4 | Sensitive data protected, no hardcoded secrets, input validation |

Conditional Rubric Dimensions (activated by tech-context)

| Dimension | Points | Active When | |-----------|--------|-------------| | I. Framework & Infra | 4 | Java/Spring stack ativa | | J. API Contract | 4 | api dimension active | | K. Database Patterns | 4 | database dimension active | | L. Observability | 4 | observability dimension active | | M. DevOps / K8s | 4 | devops dimension active | | N. Events / Messaging | 4 | events dimension active | | O. Compliance | 4 | compliance dimension active | | P. Performance | 4 | performance dimension active | | Q. TDD Process | 4 | Always (when git history available) |

Dynamic max score = 30 (base) + (4 × number of active conditional dimensions)

Specialist Report Cross-Validation

For each specialist/developer report with STATUS Rejected or Partial:

• CRITICAL or HIGH findings → reduce base rubric score in relevant sections
• Check if reported issues have been addressed in the current diff (if re-review)

Dimension Coverage Score

Each activeDimension with a corresponding report: +1 coverage point
Max coverage = total activeDimensions
Missing CRITICAL dimension: automatic NO-GO regardless of rubric score

Pattern Coverage Rubric (only when HAS_APP_PATTERNS=true)

Cross-reference each pattern listed in application-patterns.md against the ## Pattern Breaks sections from ALL specialist reports:

For each pattern P in APP_PATTERNS_CONTEXT:
  1. Collect all "Pattern Breaks" mentions of P across specialist reports.
  2. Determine status:
     - COMPLIANT   → no break reported for P in any specialist report
     - PARTIAL     → break reported but non-critical; specialist noted workaround
     - BREAK       → explicit break reported by at least one specialist (severity HIGH or CRITICAL)
     - N/A         → all specialists marked P as "not applicable for this story"
  3. Record in Pattern Coverage table (included in Phase 4 report structure).

Pattern Coverage score contribution:

• Each COMPLIANT or N/A pattern: no penalty
• Each PARTIAL pattern: -2 points from base rubric
• Each BREAK (severity HIGH): -4 points from base rubric
• Each BREAK (severity CRITICAL): automatic NO-GO override

When HAS_APP_PATTERNS=false: skip this rubric entirely (do not penalize).

Phase 4 — Verdict & Artifacts

Decision Criteria

| Condition | Decision | |-----------|----------| | Score >= 85% of dynamic max AND zero CRITICAL/HIGH issues AND all CRITICAL dimensions covered | GO | | Score >= 70% AND no CRITICAL issues AND no missing CRITICAL dimensions | GO WITH RESERVATIONS | | Score < 70% OR any CRITICAL issue OR missing CRITICAL dimension | NO-GO | | ANY test failure | NO-GO (automatic) | | Coverage < 95% line OR < 90% branch | NO-GO (automatic) |

Report Structure

## Tech Lead Review — [Story/PR Title]

### Verdict: GO / NO-GO / GO-WITH-RESERVATIONS
**Score: XX/{dynamic_max}**

### Architecture Plan Alignment
[Summary of whether the arch plan was implemented correctly]

### Dimension Coverage Audit
| Dimension | Expected | Report Found | Status |
|-----------|----------|--------------|--------|
| Security  | ✅       | ✅           | Covered |
| QA        | ✅       | ✅           | Covered |
| ...       | ...      | ...          | ... |

### Specialist Report Summary
| Specialist | Score | Status | Key Findings |
|------------|-------|--------|--------------|
| Security   | /30   | ...    | ... |
| QA         | /36   | ...    | ... |
| ...        | ...   | ...    | ... |

### Base Rubric Results
[Per-section scores and findings]

### Conditional Rubric Results
[Only sections activated by tech-context]

### Pattern Coverage (application-patterns.md)
> Only rendered when `docs/architecture/application-patterns.md` exists.
| Pattern | Path | Mandatory | Status | Findings / Observations |
|---------|------|-----------|--------|-------------------------|
| {{pattern_name}} | {{path}} | {{true\|false}} | ✅ Compliant / ⚠️ Partial / ❌ Break / ➖ N/A | {{summary}} |

### Reservas Permitidas (GO-WITH-RESERVATIONS)
> Only rendered when verdict is GO-WITH-RESERVATIONS.
> Lists all items that did not block the GO but MUST be resolved before final merge.
| # | Item | Specialist | Severity | Prazo Recomendado | O que está pendente |
|---|------|-----------|----------|-------------------|---------------------|

### Required Changes (if NO-GO)
1. [Specific change required]
2. [Specific change required]

### Recommendations (non-blocking)
- [Suggestions]

Dashboard and Remediation Tracker Update

After issuing verdict:

1. Update .aikittools/features/feature-XXXX/reviews/dashboard-story-XXXX-YYYY.md — append Tech Lead score and verdict
2. Update .aikittools/features/feature-XXXX/reviews/remediation-story-XXXX-YYYY.md — mark Tech Lead FAILED items as Open

Phase 5 — Emit Frontmatter (MANDATORY)

Emit YAML frontmatter conforming to review-frontmatter-1.0.json schema:

---
schema-version: "1.0"
generated-by: "x-review-tech-lead@<sha>"
decision: GO | NO-GO | GO-WITH-RESERVATIONS
score: XX
score-max: YY  # dynamic max
dimensions-active: [security, qa, ...]
dimensions-covered: [security, qa, ...]
dimensions-missing: []
specialist-reports-read: [security, qa, ...]
developer-reports-read: [java, angular, ...]
pattern-breaks: []   # list of pattern names with status BREAK; empty if all compliant or N/A
reservations: []     # list of items in "Reservas Permitidas" table; empty for GO/NO-GO
checklist:
  passed: NN
  total: NN
  failed-sections: []
---

Validate via audit-review-frontmatter.sh → abort with REVIEW_FRONTMATTER_INVALID on non-zero (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 reports found in reviews/ | Warn and proceed with rubric-only review; note missing context | | Arch plan not found | Log INFO, use tech-context.config.json only | | Missing CRITICAL dimension report | Automatic NO-GO; surface in Dimension Coverage Audit | | Tests fail | Automatic NO-GO regardless of score | | Coverage below gates | Automatic NO-GO | | Phase 5 frontmatter audit fails | Abort with REVIEW_FRONTMATTER_INVALID (Rule 24) |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-review-pr | called-by | x-review-pr Phase 3 invokes this skill | | x-review-specialist | reads reports from | Reads all specialist reports to cross-validate | | x-review-developer | reads reports from | Reads all developer reports to assess coverage | | x-internal-plan-arch-story | reads output of | Reads arch plan from .aikittools/.../plans/arch-story-*.md | | x-internal-evaluate-tech-context | calls | Derives active dimensions from tech-context | | x-internal-verify-phase-gates | calls | Rule 25 Invariant 4 gate enforcement | | audit-review-frontmatter.sh | calls (Phase 5) | Mandatory frontmatter validation | | _TEMPLATE-TECH-LEAD-REVIEW.md | reads | Output format template | | _TEMPLATE-CONSOLIDATED-REVIEW-DASHBOARD.md | updates | Cumulative across rounds |