# Fix

> Fix QA issues from the current implementation revision using TDD, then automatically re-runs authorized QA.

- Skill: `mrlyk/fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrlyk/fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/fix

---


# Fix QA Issues

从 `verification.md` 与 `trace.jsonl` 恢复当前实现版本对应的 QA run，再读取该 run 明确绑定的本地原始问题源。review、QA 和 verification findings 全部通过同一确定性分组协议修复。

## Entry Ownership and Prerequisites

独立调用本 skill 时，它只处理用户已授权的 QA 修复：用户必须已在 `qa` 阶段选择 `superharness qa --task <task> --decision fix`。`verification.md` 中的 `decision` 必须为 `fix`，且 `run_id`、`implementation_head`、`issue_sources` 必须与 `trace.jsonl` 的原始 `qa:result` 一致。历史 evals run、旧 HEAD、未绑定文件或摘要不匹配的结果不可作为修复输入。

review 与 final verification 的父控制器只复用下方 **Shared Finding Group Protocol**，不套用 QA prerequisite、QA 重跑或 QA 证据恢复步骤。这样所有来源共享同一分组与集成语义，同时保留各自的入口授权。

## Process

### Step 1: Load Issues

```bash
cat .superharness/tasks/{task}/verification.md
cat .superharness/tasks/{task}/trace.jsonl
```

按以下顺序恢复原始问题，任一步不满足都停止修复并报告当前 QA 证据不可恢复：

1. 从 `verification.md` 读取当前 `Verified Implementation HEAD` 与 `QA Evidence`，确认 `decision: fix`，并记录 `run_id`、`implementation_head`、`issue_sources`。
2. 在 `trace.jsonl` 中查找 `ref` 等于该 `run_id`、`implementation_head` 等于当前 Verified Implementation HEAD 的 `qa:result`；其 `issue_sources` 必须与 verification 完全一致。
3. 对每个 source 只接受任务目录内的相对路径，确认文件存在，并用 `shasum -a 256 <path>` 核对持久化的 `sha256`。
4. 只有上述核对通过后，才从对应 `qa-issues.json` 或 `qa-results-<service>.json` 读取 issue 明细。禁止扫描 `evals/` 后选择“最新”run，也禁止回退到其他输出文件。
5. 从已验证的原始文件中过滤 `status: "pending"` issues，按 critical → major → minor → suggestion 排序。

If no pending issues, report "No pending QA issues" and stop.

`verification.md` 与 `trace.jsonl` 只持久化 source path、service、SHA-256、run/revision 和计数；issue message、file、line、fix_hint 等明细始终保留在本地原始问题源中。禁止创建 `qa-summary.json`。

### Step 2: Shared Finding Group Protocol

在原始 review/QA/verification evidence 中保留稳定 ID、severity、source 和 `AFFECTED_TASKS`。调用 CLI 时只写 task-local 投影，exact schema 为 `{"findings":[{"id":"F1","affectedTaskIds":[1]}]}`。把 `AFFECTED_TASKS` 转成 `affectedTaskIds`；缺失时省略该键，CLI 会放入保守串行组。错误或额外键会以 `INVALID_FINDINGS_INPUT` 失败。

```bash
superharness task group-findings {task} --input .superharness/tasks/{task}/findings.json --json
```

CLI 返回的连通分量是唯一分组事实。Do not recalculate or change CLI groups. 同一 group 内的 findings serially within that group；不同 group 仅在 CLI 返回为独立时才可并行。

Lite 缺少分组 metadata，父控制器必须使用一个保守串行组，并且不得调用 `task group-findings`。

所有 group agent 在同一个任务 worktree 内工作。控制器在同一个 dispatch turn 派发所有独立 group agent，并等待全部 group 的 focused verification 结果。每个 group 以精确 pathspec 提交自己的 fix commit（`git add -- <files>` 加 `git commit --only -- <files>`）；并发提交遇到 index.lock 或 ref lock 属显式报错，重读 HEAD 后重试。任一 group 失败或留下 blocker 时保留其改动与 commit，停止自动推进受影响的 group，不扩大修复轮数。

每个 group 派发前和结束后记录受控事件：`superharness task observe {task} fix-start --fix-group {group-id} --detail <scope>`，随后以相同 `--fix-group {group-id}` 写入 fix-pass、fix-fail 或 fix-error。独立 group 不能共用一个事件。全部成功 group 提交后，当前 HEAD 即新的实现 HEAD；`FIX_GROUP_EVIDENCE` 记录每组 finding ids、fix commit 与 focused commands。

### Step 3: Repair Each Finding Group (focused TDD)

每个 group agent 只读取本组 finding 和对应 source evidence，并且：

1. 为本组下一个 finding 写失败测试（RED）。
2. 以最小改动修复并运行该测试（GREEN）。
3. 对每项重复，直到本组关闭或阻塞。
4. 只运行计划或 finding 明确授权的 focused verification；不得以无范围完整门禁替代 focused verification。
5. 在共享任务 worktree 内以精确 pathspec 创建一个 fix commit，并把 commit 与 focused evidence 交回控制器。

### Step 4: Close Findings and Re-Review

所有成功 group 的 fix commit 落到分支形成新的实现 HEAD 后，按 finding 来源分流：

- **review-source findings**：`superharness task transition {task} check` 后对本轮全部 fix diff 做一次复看（fix-diff recheck）：派一个 `check` 轴子代理只读 fix diff、原 findings 与波及面，不重跑全量两轴审查。复看仍有 Critical/Major 时停下交用户决定方向，不自动重试；复看通过后把每个 fix commit 与复看结论记入 `verification.md` 的 Final Review 段。
- **QA-source fixes**：走既有授权 QA 重跑（Step 5）。
- **verification-source fixes**：走 finishing 的新一轮 full non-E2E gate。

QA and verification findings use this same grouping protocol。任何未关闭 blocker 或超过既有 `max_fix_rounds` 都停止自动修复并交由用户决策。

### Step 5: Re-run QA

重新 complete 后，已获授权的 QA 自动重跑：

```bash
superharness qa --task .superharness/tasks/{task}
```

This performs incremental verification:
- Re-runs all deterministic checks
- Only re-evaluates rubric dimensions related to fixed issues

### Step 6: Check Convergence

If new issues appear or regressions are detected:
- Regression issues (previously fixed, now failing again) get severity bumped one level
- If `fix_round` exceeds `max_fix_rounds` (default 3), mark remaining issues as `"escalated"`
- Report escalated issues to user for manual intervention

## Anti-Oscillation Rules

- **Max 3 fix rounds** per issue (configurable in config.yaml)
- **Regression detection**: same issue id reappearing after fix → severity bumped
- **Two consecutive regressions** → auto-escalate to human
- **Never** fix suggestion-level issues automatically (only if user requests)

## Red Flags

- **Never** skip the failing test step — even for "obvious" fixes
- **Never** mark an issue as fixed without focused verification
- **Never** exceed max_fix_rounds without escalating
- **Never** bypass `task group-findings` or split a CLI group for DAG tasks; Lite uses the required single conservative group
- **Never** read an issue source unless its run, revision, task-local path and SHA-256 all match the persisted QA result