@gtrabanco/pi-agentic-workflow 0.2.0 → 0.4.0

package/skills/loop-review-fold/SKILL.md

@@ -1,191 +0,0 @@
----
-name: loop-review-fold
-user-invocable: true
-version: 3.0.0
-argument-hint: <NN> | --fix <issue-number>
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Run the simple review-change/fold-findings loop for an open feature or fix
-  unit. Inspect persisted review evidence first so a previous review resumes
-  with fold-findings instead of reviewing the same candidate again. Unresolved
-  findings go to triage-issue with an immediate-fix instruction; oversized
-  findings become a user-confirmed plan-feature or plan-fix replan with new
-  phases. Triggers: "loop-review-fold", "review and fold this PR", "run the
-  review fold loop".
----
-
-# Review / Fold Loop
-
-Run one small state loop over the current feature or fix unit:
-
-```text
-review-change ── findings ──▶ fold-findings ── changed HEAD ──▶ review-change
-       ▲                              │
-       └──────── current PASS ◀───────┘
-                                      └─ unresolved ─▶ triage-issue
-```
-
-This skill is a router, not a third review or repair implementation. It reads
-the durable evidence left by `review-change` and `fold-findings`, chooses the
-next action, and stops when a user decision or manual phase execution is
-required. Never merge, create an unrelated issue, or silently discard a
-finding.
-
-## Turn contract
-
-```text
-✓ The feature/fix unit, branch, PR, current HEAD, acceptance, and finding ledger were checked
-✓ The first action was selected from persisted evidence: PASS, review-change, or fold-findings
-✓ review-change ran only when no current review result required fold-findings first
-✓ A successful fold was followed by review-change on the new HEAD
-✓ Every unresolved finding is named and routed to triage-issue --prioritize-now
-✓ An oversized finding routes to plan-feature or plan-fix, new P<n> phases, and manual user execution
-✓ No merge, unrelated issue, acceptance weakening, or silent finding drop occurred
-✓ The fixed result and the closing → Next: block are the final output
-```
-
-Any unchecked box means the turn is not done.
-
-## When to use
-
-Use after `execute-phase` opens the unit PR, or when the user asks to review and
-fold an open feature or fix. The argument identifies the unit:
-
-- `/loop-review-fold <NN>` for a feature unit.
-- `/loop-review-fold --fix <issue-number>` for a fix unit.
-
-Do not use this entrypoint to edit this skill, inspect its implementation as the
-requested deliverable, or invent a target when the unit argument is missing.
-
-## Step 0 — Discover the project (always first)
-
-Read the target project's agent guide and documentation map. Then verify the
-target unit, current branch, open PR, remote HEAD, frozen acceptance artifact,
-the latest `review-change` result/receipt, and the unit's `review-findings.md`.
-Use repository and forge commands required by the project's own conventions.
-Narration, an old chat result, or a clean worktree alone is not evidence.
-
-If the target, PR, acceptance, or ledger cannot be verified, stop with
-`BLOCKED` and name the exact missing input and recovery command. Do not create
-replacement artifacts in this router.
-
-## Process
-
-Apply this first-match table exactly:
-
-| Persisted state on the current HEAD | First action |
-|---|---|
-| Exact current `REVIEW-PASS`, matching acceptance, and no open finding rows | `PASS`; do not run either skill |
-| A review result exists for this HEAD and it leaves any `folded: no` row | `fold-findings` on the complete open queue |
-| No usable current review result and no open queue | `review-change` on the current HEAD |
-
-Then continue as follows:
-
-1. Run the selected skill in its own fresh context and follow that skill's
-   contract literally. This loop does not copy its internal checklist.
-2. If `review-change` returns `REVIEW-PASS`, verify its exact-HEAD receipt and
-   zero open rows, then return `PASS`.
-3. If `review-change` returns findings, run `fold-findings` for every open
-   `fix-now` row. Do not start another review before that queue is processed.
-4. If `fold-findings` changes and pushes the candidate, run `review-change` on
-   that new HEAD. Never review an unchanged HEAD a second time.
-4a. Before step 5, split the open queue by **owning stage** (the `route` cell each
-    `review-change` finding carries: `product | plan | source | environment |
-    runtime`). Only `source`, `environment` and `runtime` rows may be folded or
-    triaged here. A `plan`-owned row stops the loop with `BLOCKED` and hands off to
-    `/plan-feature <unit>` (fix: `/plan-fix <n>`) for one root-caused re-cut, then
-    `/review-plan <unit>`; a `product`-owned row goes to `/design-feature <unit>`
-    then `/review-spec <unit>`. Folding repairs the candidate; it cannot repair the
-    authority that describes it, so never fold a row whose artifact of record is a
-    planning document, and never send one to `triage-issue` to make it disappear.
-4b. On entering a **second** local review→fold cycle for the same finding family,
-    diagnose before editing again: emit the `CONVERGENCE-ANOMALY` report defined by
-    `pre-execution-review` (repeated vs new ids, snapshot digest and
-    `artifactRevisionId` move, what was missed, owning stage, why the prior
-    repair failed, route to owner) and continue from the owner it names. A third
-    blind edit is not a repair attempt, and no cycle count here is ever hidden.
-
-5. If any finding remains unresolved (`DISPUTED`, `BLOCKED`, `REPLAN`, or an
-   open row left after folding), stop the loop and hand every such ID to:
-
-   ```text
-   /triage-issue --prioritize-now <unit-or-fix> F1 F2 ...
-   ```
-
-   Tell `triage-issue` to try to resolve every named finding immediately. It
-   may route a small correction back to the current unit, but it must not hide,
-   downgrade, or postpone a review finding merely to finish the loop.
-6. When the smallest correct correction is too large for the current fold,
-   `triage-issue` must choose a replan route: re-run `/plan-feature <slug>` for
-   a feature or `/plan-fix <issue-number>` for a fix, append explicit new
-   `P<n>` phases to the unit's SPEC, and stop. The loop then asks the user to
-   execute those phases manually with `/execute-phase <unit> P<n>` (or the
-   fix equivalent) before invoking this loop again.
-
-Do not use a hidden retry count. The loop ends at the first `PASS`, blocked
-prerequisite, unresolved finding, or required manual replan. A later user
-invocation starts from the newly persisted state. The loop files nothing: an
-unresolved finding never becomes a forge issue from here, and deferring one out of
-the unit requires the user to amend the governing SPEC first.
-
-## Fixed output contract
-
-Return exactly:
-
-```text
-REVIEW-FOLD LOOP — PASS | TRIAGE-REQUIRED | BLOCKED
-Unit: <unit> · PR: <url> · HEAD: <sha>
-First action: PASS | review-change | fold-findings
-Review: <PASS | FAIL | not-run> · Fold: <changed | unchanged | not-run>
-Owned elsewhere: <plan → /plan-feature + /review-plan | product → /design-feature
-  + /review-spec | none>
-Unresolved: <F1 + F2 + … | none>
-Evidence: <one concise line explaining the selected action and result>
-
-→ Next: <one concrete command or user action> — <why>
-  · <alternative when applicable>
-```
-
-Use `TRIAGE-REQUIRED` whenever a finding needs `triage-issue`, a replan, or a
-user decision. Replace every placeholder, list each actual finding ID exactly
-once joined with ` + `, and never emit a literal ellipsis.
-
-## Guardrails
-
-Allowed: read target evidence, invoke `review-change`, invoke `fold-findings`,
-and route unresolved findings to `triage-issue`.
-
-Forbidden: implementing a fix in this router, editing review classifications,
-marking findings folded, creating unrelated issues, weakening acceptance or
-checks, merging, or claiming that a user has implemented newly planned phases.
-Also forbidden: folding a `plan`- or `product`-owned finding, re-editing on a
-second local cycle before the convergence diagnosis is reported, and treating an
-absent pre-execution PASS as foldable debt.
-
-## Relationship to other skills
-
-`execute-phase` hands off here after a unit PR opens. `review-change` owns
-read-only classification and the SHA-bound pass receipt. `fold-findings` owns
-the actual correction and ledger tick. `triage-issue --prioritize-now` owns the
-decision for unresolved findings and routes oversized work to `plan-feature` or
-`plan-fix`; the user then executes the appended phases manually.
-
-## Portability (agents other than Claude Code)
-
-If fresh contexts or subagents are unavailable, invoke each delegated skill in
-a new conversation and re-read the persisted HEAD, receipt, and ledger before
-continuing. If the host has no slash-command menu, open each named `SKILL.md`
-and follow it literally. Never claim a clean review after the same context
-implemented the correction.
-
-## Done when
-
-The current HEAD has a verified `REVIEW-PASS` and no open findings, or every
-remaining finding has a concrete triage/replan hand-off and the user has been
-told to implement the new phases manually.
-
-→ Next: print the matching terminal route from the fixed output contract — never send a non-PASS result to audit-pr
-  · PASS → /audit-pr — consume the current exact-HEAD REVIEW-PASS
-  · TRIAGE-REQUIRED → /triage-issue --prioritize-now <unit> F<k> — resolve every actual unresolved finding, then plan/execute new phases manually
-  · BLOCKED → the exact recovery command — supply the missing target, PR, acceptance, or ledger input before re-running the loop