@levnikolaevich/ln-510-quality-coordinator

---
name: ln-510-quality-coordinator
description: "Coordinates code quality: ln-511 metrics, ln-512 cleanup, inline agent review (Codex + Gemini), ln-513 regression, ln-514 log analysis. Returns quality_verdict + aggregated results."
license: MIT
---

> **Paths:** File paths (`shared/`, `references/`, `../ln-*`) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

# Quality Coordinator

Sequential coordinator for code quality pipeline. Invokes workers (ln-511 → ln-512 → ln-513 → ln-514), runs inline agent review in parallel with Phases 5-8, merges all results, and returns quality_verdict.

## Inputs

| Input | Required | Source | Description |
|-------|----------|--------|-------------|
| `storyId` | Yes | args, git branch, kanban, user | Story to process |

**Resolution:** Story Resolution Chain.
**Status filter:** To Review

## Purpose & Scope
- Invoke ln-511-code-quality-checker (metrics, MCP Ref, static analysis)
- Invoke ln-512-tech-debt-cleaner (auto-fix safe findings from ln-511)
- Run inline agent review (Codex + Gemini in parallel on cleaned code)
- Run Criteria Validation (Story dependencies, AC-Task Coverage, DB Creation Principle)
- Run linters from tech_stack.md
- Invoke ln-513-regression-checker (test suite after all changes)
- Invoke ln-514-test-log-analyzer (classify errors, assess log quality)
- Return quality_verdict + aggregated results
- Calculate quality_verdict per normalization matrix + `references/gate_levels.md`

## When to Use
- **Invoked by ln-500-story-quality-gate** Phase 2
- All implementation tasks in Story status = Done

## Workflow

### Phase 0: Resolve Inputs

**MANDATORY READ:** Load `shared/references/input_resolution_pattern.md`

1. **Resolve storyId:** Run Story Resolution Chain per guide (status filter: [To Review]).

### Phase 1: Discovery

1) Auto-discover team/config from `docs/tasks/kanban_board.md`
2) Load Story + task metadata from Linear (no full descriptions)
3) **Collect git scope** (sets `changed_files[]` for ln-511 via coordinator context):
   **MANDATORY READ:** Load `shared/references/git_scope_detection.md`
   Run algorithm from guide → build `changed_files[]`

**Fast-track mode:** When invoked with `--fast-track` flag (readiness 10/10), run Phase 2 with `--skip-mcp-ref` (metrics + static only, no MCP Ref), skip Phase 3 (ln-512), Phase 4 (agent review). Run Phase 5 (criteria), Phase 6 (linters), Phase 7 (ln-513), Phase 8 (ln-514).

### Phase 2: Code Quality (delegate to ln-511 — ALWAYS runs)

> **MANDATORY STEP:** ln-511 invocation required in ALL modes.
> **Full gate:** ln-511 runs everything (metrics + MCP Ref + static analysis).
> **Fast-track:** ln-511 runs with `--skip-mcp-ref` (metrics + static analysis only — catches complexity, DRY, dead code without expensive MCP Ref calls).

1) **Invoke ln-511-code-quality-checker** via Skill tool
   - Full: ln-511 runs code metrics, MCP Ref validation (OPT/BP/PERF), static analysis
   - Fast-track: ln-511 runs code metrics + static analysis only (skips OPT-, BP-, PERF- MCP Ref checks)
   - Returns verdict (PASS/CONCERNS/ISSUES_FOUND) + code_quality_score + issues list
2) **If ln-511 returns ISSUES_FOUND** -> aggregate issues, continue (ln-500 decides action)

**Invocation:**
```
# Full gate:
Skill(skill: "ln-511-code-quality-checker", args: "{storyId}")
# Fast-track:
Skill(skill: "ln-511-code-quality-checker", args: "{storyId} --skip-mcp-ref")
```

### Phase 3: Tech Debt Cleanup (delegate to ln-512 — SKIP if --fast-track)

> **MANDATORY STEP (full gate):** ln-512 invocation required. Safe auto-fixes only (confidence >=90%).
> **Fast-track:** SKIP this phase.

1) **Invoke ln-512-tech-debt-cleaner** via Skill tool
   - ln-512 consumes findings from ln-511 output (passed via coordinator context)
   - Filters to auto-fixable categories (unused imports, dead code, deprecated aliases)
   - Applies safe fixes, verifies build integrity, creates commit
2) **If ln-512 returns BUILD_FAILED** -> all changes reverted, aggregate issue, continue

**Invocation:**
```
Skill(skill: "ln-512-tech-debt-cleaner", args: "{storyId}")
```

### Phase 4: Agent Review Launch (SKIP if --fast-track)

> **MANDATORY STEP (full gate):** Launches agents in background, results merged in Phase 9.
> **Fast-track:** SKIP this phase.

**MANDATORY READ:** Load `shared/references/agent_review_workflow.md`, `shared/references/agent_delegation_pattern.md`

4a) **Health Check** (per shared workflow "Step: Health Check"):
    - Read `docs/environment_state.json` → exclude agents with `disabled: true`
    - Run `python shared/agents/agent_runner.py --health-check` for remaining agents
    - If 0 agents → agent review SKIPPED, go to Phase 5
4b) **Get references:** `get_issue(storyId)` + `list_issues(parent=storyId, status=Done)` (exclude test tasks)
4c) **Build prompt:** Assemble from `shared/agents/prompt_templates/review_base.md` + `modes/code.md` (per shared workflow "Step: Build Prompt"), replace `{story_ref}`, `{task_refs}`. Save to `.agent-review/{identifier}_codereview_prompt.md`
4d) **Launch BOTH agents** as background tasks (per shared workflow)
    → Continue to Phase 5 (Criteria Validation), Phase 6 (Linters), Phase 7 (Regression), Phase 8 (Log Analysis) while agents work

### Phase 5: Criteria Validation

**MANDATORY READ:** Load `references/criteria_validation.md`

| Check | Description | Fail Action |
|-------|-------------|-------------|
| #1 Story Dependencies | No forward deps within Epic | [DEP-] issue |
| #2 AC-Task Coverage | STRONG/WEAK/MISSING scoring | [COV-]/[BUG-] issue |
| #3 DB Creation Principle | Schema scope matches Story | [DB-] issue |

### Phase 6: Linters
**MANDATORY READ:** `shared/references/ci_tool_detection.md` (Discovery Hierarchy + Command Registry)

1) Detect lint/typecheck commands per ci_tool_detection.md discovery hierarchy
2) Run all detected checks (timeouts per guide: 2min linters, 5min typecheck)
3) **If any check fails** -> aggregate issues, continue

### Phase 7: Regression Tests (delegate to ln-513)

1) **Invoke ln-513-regression-checker** via Skill tool
   - Runs full test suite, reports PASS/FAIL
   - Runs AFTER ln-512 changes to verify nothing broke
2) **If regression FAIL** -> aggregate issues, continue

**Invocation:**
```
Skill(skill: "ln-513-regression-checker", args: "{storyId}")
```

### Phase 8: Test Log Analysis (delegate to ln-514 — runs after ln-513)

1) **Invoke ln-514-test-log-analyzer** via Skill tool with context instructions
   - Only Real Bugs affect quality verdict; log quality issues are informational
2) **If ln-514 returns REAL_BUGS_FOUND** -> aggregate issues, continue
3) **If ln-514 returns NO_LOG_SOURCES** -> status ignored, continue
4) Post ln-514 report as Linear comment on story

**Invocation:**
```
Skill(skill: "ln-514-test-log-analyzer", args: "review logs since test run start, expected errors from negative test cases")
```

### Phase 9: Agent Merge (runs after Phase 8, when agent results arrive — SKIP if --fast-track or agents SKIPPED)

**MANDATORY READ:** Load `shared/references/agent_review_workflow.md` (Critical Verification + Debate), `shared/references/agent_review_memory.md`

9a) **Wait for agent results** — read result files as they arrive (process-as-arrive pattern)
9b) **Critical Verification + Debate** per shared workflow — Claude evaluates each suggestion on merits
9c) **Merge accepted suggestions** into issues list (SEC-, PERF-, MNT-, ARCH-, BP-, OPT-)
    - If `area=security` or `area=correctness` → escalate aggregate to CONCERNS
9d) **Save review summary** to `.agent-review/review_history.md`

### Phase 10: Calculate Verdict + Return Results

**MANDATORY READ:** Load `references/gate_levels.md`

#### Step 10.1: Normalize Component Results

Map each component status to FAIL/CONCERN/ignored using this matrix:

| Component | Status | Maps To | Penalty |
|-----------|--------|---------|---------|
| quality_check | PASS | -- | 0 |
| quality_check | CONCERNS | CONCERN | -10 |
| quality_check | ISSUES_FOUND | FAIL | -20 |
| criteria_validation | PASS | -- | 0 |
| criteria_validation | CONCERNS | CONCERN | -10 |
| criteria_validation | FAIL | FAIL | -20 |
| linters | PASS | -- | 0 |
| linters | FAIL | FAIL | -20 |
| regression | PASS | -- | 0 |
| regression | FAIL | FAIL | -20 |
| tech_debt_cleanup | CLEANED | -- | 0 |
| tech_debt_cleanup | NOTHING_TO_CLEAN | -- | 0 |
| tech_debt_cleanup | BUILD_FAILED | FAIL | -20 |
| tech_debt_cleanup | SKIPPED | ignored | 0 |
| agent_review | CODE_ACCEPTABLE | -- | 0 |
| agent_review | SUGGESTIONS (security/correctness) | CONCERN | -10 |
| agent_review | SKIPPED | ignored | 0 |
| log_analysis | CLEAN | -- | 0 |
| log_analysis | WARNINGS_ONLY | -- | 0 |
| log_analysis | REAL_BUGS_FOUND | FAIL | -20 |
| log_analysis | SKIPPED / NO_LOG_SOURCES | ignored | 0 |

#### Step 10.2: Calculate Quality Verdict

```
fail_count = count of components mapped to FAIL
concern_count = count of components mapped to CONCERN
quality_score = 100 - (20 * fail_count) - (10 * concern_count)

# Fast-fail override: any FAIL -> verdict is FAIL regardless of score
IF fail_count > 0:
  quality_verdict = FAIL
ELSE IF quality_score >= 90:
  quality_verdict = PASS
ELSE IF quality_score >= 70:
  quality_verdict = CONCERNS
ELSE:
  quality_verdict = FAIL
```

#### Step 10.3: Return Results

```yaml
quality_verdict: PASS | CONCERNS | FAIL
quality_score: {0-100}
fail_count: {N}
concern_count: {N}
ignored_components: [tech_debt_cleanup, agent_review]  # only if SKIPPED
quality_check: PASS | CONCERNS | ISSUES_FOUND
code_quality_score: {0-100}
agent_review: CODE_ACCEPTABLE | SUGGESTIONS | SKIPPED
criteria_validation: PASS | CONCERNS | FAIL
linters: PASS | FAIL
tech_debt_cleanup: CLEANED | NOTHING_TO_CLEAN | BUILD_FAILED | SKIPPED
regression: PASS | FAIL
log_analysis: CLEAN | WARNINGS_ONLY | REAL_BUGS_FOUND | SKIPPED
issues:
  - {id: "SEC-001", severity: high, finding: "...", source: "ln-511"}
  - {id: "OPT-001", severity: medium, finding: "...", source: "agent-review"}
  - {id: "DEP-001", severity: medium, finding: "...", source: "criteria"}
  - {id: "LINT-001", severity: low, finding: "...", source: "linters"}
```

**TodoWrite format (mandatory):**
```
- Invoke ln-511-code-quality-checker (in_progress)
- Invoke ln-512-tech-debt-cleaner (pending)
- Launch agent review (background) (pending)
- Criteria Validation (Story deps, AC coverage, DB schema) (pending)
- Run linters from tech_stack.md (pending)
- Invoke ln-513-regression-checker (pending)
- Invoke ln-514-test-log-analyzer (pending)
- Merge agent review results (pending)
- Calculate quality_verdict + return results (pending)
```

## Worker Invocation (MANDATORY)

| Phase | Worker | Context |
|-------|--------|---------|
| 2 | ln-511-code-quality-checker | Shared (Skill tool) — code metrics, MCP Ref, static analysis |
| 3 | ln-512-tech-debt-cleaner | Shared (Skill tool) — auto-fix safe findings from ln-511 |
| 4 | Inline agent review (Codex + Gemini) | Background — launched after ln-512, merged in Phase 9 |
| 7 | ln-513-regression-checker | Shared (Skill tool) — full test suite after all changes |
| 8 | ln-514-test-log-analyzer | Shared (Skill tool) — error classification + log quality after ln-513 |

**All workers:** Invoke via Skill tool — workers see coordinator context. Agent review runs inline (no Skill delegation).

**Anti-Patterns:**
- Running mypy, ruff, pytest directly instead of invoking ln-511/ln-513
- Skipping agent health check or not launching agents in Phase 4
- Auto-fixing code directly instead of invoking ln-512
- Marking steps as completed without invoking the actual skill
- Skipping verdict calculation or returning raw results without quality_verdict

## Critical Rules
- Always calculate quality_verdict per normalization matrix + gate_levels.md. Final gate_verdict is ln-500's responsibility (includes tests, NFR, waivers)
- Single source of truth: rely on Linear metadata for tasks
- Language preservation in comments (EN/RU)
- Do not create tasks or change statuses; ln-500 decides next actions

## Definition of Done

- [ ] ln-511 invoked (ALWAYS — full or `--skip-mcp-ref` in fast-track), code quality score returned
- [ ] ln-512 invoked (or skipped if --fast-track), tech debt cleanup results returned
- [ ] Agent review executed inline (or skipped if --fast-track), results merged in Phase 9
- [ ] Criteria Validation completed (3 checks)
- [ ] Linters executed
- [ ] ln-513 invoked, regression results returned
- [ ] ln-514 invoked, log analysis results returned (or SKIPPED/NO_LOG_SOURCES)
- [ ] quality_verdict calculated + aggregated results returned

## Phase 11: Meta-Analysis

**MANDATORY READ:** Load `shared/references/meta_analysis_protocol.md`

Skill type: `review-coordinator` (with agents). Run after all phases complete. Output to chat using the `review-coordinator — with agents` format.

## Reference Files
- Criteria Validation: `references/criteria_validation.md`
- Gate levels: `references/gate_levels.md`
- Workers: `../ln-511-code-quality-checker/SKILL.md`, `../ln-512-tech-debt-cleaner/SKILL.md`, `../ln-513-regression-checker/SKILL.md`, `../ln-514-test-log-analyzer/SKILL.md`
- Agent review workflow: `shared/references/agent_review_workflow.md`
- Agent delegation pattern: `shared/references/agent_delegation_pattern.md`
- Agent review memory: `shared/references/agent_review_memory.md`
- Review templates: `shared/agents/prompt_templates/review_base.md` + `modes/code.md`
- Caller: `../ln-500-story-quality-gate/SKILL.md`
- Test planning (separate coordinator): `../ln-520-test-planner/SKILL.md`
- Tech stack/linters: `docs/project/tech_stack.md`

---
**Version:** 7.0.0
**Last Updated:** 2026-02-09