Karvey Iterate

Karvey Iterate — The Iteration Engine

Afán = don't stop until the result is really achieved. This skill is where that lives: it takes what testing/QA/real-runtime surfaced and sends each item back to where it belongs, instead of letting it die at the end of a linear pipeline.

Purpose

The pipeline (0→12) is the happy path. karvey-iterate is the feedback brain that closes the loop. It does ONE thing: read the findings inbox and route each finding to its correct edge. The phase skills (test, qa, browse) only observe and classify; this skill routes. Keeping routing in one place is the whole design.

Read these rules before acting:

• karvey/rules/iteration-loop.md — the three feedback edges, findings.md, the spec-revision sub-cycle, convergence.
• karvey/rules/incident-tracking.md — the BUG-NN tracker with state history.
• karvey/rules/backlog.md — the dual (Markdown + ClickUp) discovery backlog.
• karvey/rules/phase-close.md — the close ritual.

When to run it

• After test / qa / browse produced findings.
• Any time a finding appears mid-flow ("this spec was wrong", "a new bug showed up", "good idea but out of scope").
• The orchestrator routes you here whenever findings.md has open items.

Execution steps

Step 1 — Load context

Read:

• docs/spec/changes/{change-id}/spec.json
• docs/spec/changes/{change-id}/findings.md (the inbox; if it doesn't exist, there's nothing to iterate — tell the user and stop)
• docs/spec/changes/{change-id}/requirements.md and spec-delta.md (for spec-gap routing)
• docs/spec/project.json (management, repos, backlog_list_id)

If --finding F-NN is given, process only that finding. Otherwise process every open finding.

Step 2 — Confirm/correct the classification of each finding

For each open finding, re-judge its type with the litmus test from iteration-loop.md:

• "Spec is right, code is wrong" → bug
• "If we'd specified this correctly, impl would differ" → spec-gap
• "Good idea, but a different change" → emergent

If a finding's type is ambiguous or its routing is irreversible (re-opening requirements, creating a new change), confirm with the user via AskUserQuestion. In --auto mode, route the unambiguous ones and only stop for the ambiguous/irreversible ones.

Step 3 — Route by type

3a · bug → incident tracker + QA micro-loop

1. Promote to a BUG-NN in the repo's docs/bugs_dev_testing.md (continue the incremental counter — read the file first). Fill priority, detection, component, reproduction, actual vs expected, and open the State history at DETECTADO (see incident-tracking.md).
2. Mirror to the global index docs/spec/incidents-index.md.
3. If the cause is unclear → recommend/invoke /karvey-investigate (Iron Law: no fix without investigating); paste its result as Root cause and move the incident to DIAGNOSTICADO.
4. The fix itself runs through the existing micro-loop: /karvey-impl {change-id} (fix) → /karvey-test {change-id} (incl. its regression test, Step 4C) → /karvey-qa {change-id}. The incident reaches RESUELTO only once a regression test exists.
5. If management=clickup, create/link the ClickUp task and record its id on the BUG-NN.

3b · spec-gap → re-open requirements (spec-revision sub-cycle)

1. In spec.json: set approvals.requirements.approved = false, increment iteration_count, append to revision_history (date, finding id, reason).
2. Amend only the affected requirement in requirements.md + spec-delta.md, keeping PRD traceability. Do not rewrite the whole spec.
3. Determine the ripple set — which downstream phases the spec change actually invalidates (mockup? design? architecture? tasks? impl?) — and reset their approvals.*.approved to false only where affected. Leave untouched phases approved.
4. Hand back to the user to re-approve requirements (the gate applies), then the orchestrator drives the affected phases forward again.
5. Re-run test/qa for the affected scope.

Be surgical. The point of the ripple set is to avoid redoing the whole pipeline for a one-line spec fix.

3c · emergent → discovery backlog

1. Add to docs/spec/backlog.md as BL-NN (origin = this change + finding id, rough scope, priority). See backlog.md.
2. If management=clickup, also create it in the backlog_list_id list and record the task id.
3. Never absorb emergent scope into the current change silently. It is captured, not done now.

Step 4 — Update findings status

For each routed finding, set status: routed and fill routed to (BUG-NN / spec-delta req / BL-NN) in findings.md. A finding becomes closed only when its destination resolves it (incident RESUELTO, requirement re-approved, or backlog item acknowledged).

Step 5 — Phase-close + knowledge sync

Run the phase-close ritual (phase-close.md): comment + status on management, ensure findings/backlog are synced, update spec.json, sync knowledge (knowledge-sync.md).

Step 6 — Report convergence status

🔁 Iteration routed — {change-id}  (iteration #{iteration_count})

Findings processed: {N}
  → bug:       {N}  (BUG-{list})  → QA micro-loop
  → spec-gap:  {N}  (requirements re-opened; ripple: {phases})
  → emergent:  {N}  (backlog BL-{list})

Open findings remaining: {N bug/spec-gap blocking · N emergent captured}

Convergence: {CONVERGED — no open bug/spec-gap, all emergent captured → can proceed to deploy/archive}
            {NOT YET — {what's left}}

Next step:
  - bugs:      /karvey-impl {change-id}  → /karvey-test → /karvey-qa
  - spec-gap:  re-approve requirements, then /karvey {change-id} for the next affected phase
  - emergent:  captured in backlog; promoted to change-ids at /karvey-archive

Convergence rule (the gate)

A change may proceed to deploy/archive only when findings.md has no open bug or spec-gap and all emergent are captured in the backlog (see iteration-loop.md). emergent findings never block — they only need capturing. This is how the loop is guaranteed to be honored instead of optional.

What this skill does NOT do

• It does not apply fixes (that's impl) or diagnose root cause itself for complex bugs (that's investigate).
• It does not advance spec.json:phase forward as a phase skill would — except the controlled backward transition of the spec-revision sub-cycle. It is a support skill that orchestrates feedback, not a new pipeline phase.

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md. Karvey = Afán, an ona/selknam word.