# Regressing > Runs convergence-based iterative optimization cycles wrapped by a single Discussion. Use when a topic needs repeated improvement through plan-execute-verify-feedback loops. Invoke with /regressing "topic" N (N = cycle cap, not target). Cycles continue until convergence or cap. Not for one-shot tasks — do the work directly and record it with hotfix instead. - Skill: `zipperbagcoffee/regressing` (Agent Skill) - Install (CLI): `npx skillmds add zipperbagcoffee/regressing` - Raw SKILL.md: https://api.skillmd.com/api/skills/zipperbagcoffee/regressing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ZipperBagCoffee (https://skillmd.com/u/zipperbagcoffee) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/zipperbagcoffee/regressing --- # Regressing Skill ## Core Philosophy: Result Improvement Through Iteration > **Verification Philosophy:** Follows VERIFICATION-FIRST principle from RULES (Predict → Execute → Compare). When no project verification tool exists, invoke the 'verifying' skill. > Cycles exist to improve the quality of results, not to progress through a work queue. Each cycle produces a complete result, verifies it, and the next cycle improves that result based on verified gaps. ### 3 Foundational Philosophies | Philosophy | Source | Role in regressing | |------|------|----------------------| | **Iterative Optimization** | autoresearch | Each cycle: feedback → improvement. Output becomes input | | **Parent-Owned Orchestration + Verification** | workflow | Parent-owned decisions, bounded delegation, runtime verification | | **Document Tracing** | D/P/T | Every step is documented, enabling full traceability | ## Anti-Patterns (PROHIBITED) The following patterns indicate regressing has degenerated into sequential batch execution: | Anti-Pattern | What it looks like | Correct alternative | |---|---|---| | **Pre-partitioning** | P(1) divides total work into N equal parts, assigning each to a cycle | P(1) addresses highest-impact improvements. P(2+) respond to verification gaps. Cycle count is emergent, not planned | | **Sequential pipeline** | Cycle 1 = modify, Cycle 2 = sync, Cycle 3 = version bump | Sequential tasks (version bump, cache sync, deploy) belong in the SAME cycle as separate tickets — NOT as separate cycles. Each cycle is a complete implement-verify-improve loop | | **Copy-paste feedback** | Next Direction says "continue with remaining items" | Next Direction diagnoses specific problems with evidence | | **Parent abdication** | Parent accepts a worker/reviewer claim as the final decision | Parent reopens decisive references, diffs, execution results, and side effects before completion | | **Rubber-stamp verification** | "ALL PASS — no improvement opportunities" | Orchestrator enumerates what was examined and why no improvements apply | | **Delegation ritual** | Agent count or role pairing is treated as progress or completion evidence | Delegate only bounded independent work when risk or latency justifies it; counts are never completion conditions | | **Operational steps as separate cycles** | Cycle 1 = code change, Cycle 2 = version bump + cache sync + commit | Version bump, cache sync, and commit are operational steps within a cycle's ticket(s), not independent cycles | | **Autonomous Write outside scope** | Agent writes/edits code files not covered by current ticket AC | Every code file write must trace to a ticket AC. If not covered → STOP and raise Open Question | If any of these patterns are detected during execution, the Orchestrator MUST halt and restructure before proceeding. ## Execution Procedure ### Step 1: Initialize User invokes with `/regressing "topic"` or `/regressing "topic" N`. - Run until convergence (Rule 7), with safety cap at 10 cycles. Cap is always 10 unless the user explicitly specifies a different number. Do not ask, do not infer from context. - If user writes `/regressing "topic" 5`: cap is 5. If user writes `/regressing "topic"`: cap is 10. No exceptions. ### Step 2: Open Discussion (D) Create ONE Discussion document that wraps the entire regressing session: - Invoke `/discussing "topic"` - D contains: Intent, Context, Intent Anchor (IA), goals, expected results - D MUST contain a `## Convergence Criteria` section whose items are objectively checkable by reading project documents or running a command (document status, command exit code, numeric threshold). These criteria drive Rule 7 AND the host goal evaluator (Step 2.6) — vague criteria cause wrong termination. - This D stays open throughout all cycles and closes at the end - Metadata: `[regressing: cap {N}]` After creating the Discussion document, write the regressing state file: - Path: `.crabshell/memory/regressing-state.json` - Content: `{ "active": true, "discussion": "{D-ID}", "cycle": 1, "totalCycles": {N}, "userSpecifiedN": {true|false}, "phase": "planning", "planId": null, "ticketIds": [], "startedAt": "{ISO}", "lastUpdatedAt": "{ISO}" }` - Use Bash tool: `"{NODE_PATH}" -e "require('fs').writeFileSync('{PROJECT_DIR}/.crabshell/memory/regressing-state.json', JSON.stringify({active:true, discussion:'{D-ID}', cycle:1, totalCycles:{N}, userSpecifiedN:{true|false}, phase:'planning', planId:null, ticketIds:[], startedAt:new Date().toISOString(), lastUpdatedAt:new Date().toISOString()}, null, 2))"` ### Step 2.5: Parameter Recommendation Before starting execution, recommend session parameters to the user. This happens ONCE at session start — recommended parameters apply to ALL cycles. **Recommend the following:** | Parameter | How to determine | Default | |-----------|-----------------|---------| | **Cycle cap** | From user invocation. Bare number after topic = cap. | 10 | | **Agent count** | Based on topic complexity. 2–3 for focused tasks, 3–5 for broad/complex tasks. | 3 | | **Specialist roles** | Each agent gets a distinct expert perspective relevant to the topic (e.g., "Security Auditor", "Performance Engineer", "API Design Specialist"). Roles must be non-overlapping and topic-relevant. | — | | **Model tier** | See project.md `## Model Routing` | T1 for planning, T2 for execution/verification. Project-level routing applies. | **Present to user as a compact recommendation block:** ``` 📋 Parameter Recommendation - Cycle cap: {N} - Agents: {count} — {Role1}, {Role2}, ... - Models: See project.md Model Routing (T1 → T2 per task type) Silence = proceed. Adjust any parameter by responding. ``` **Inline parameter detection:** If the user's invocation includes a bare number after the topic, it is the cycle cap (not agent count). Numbers with "명" or "agents" suffix indicate agent count. Example: `/regressing "topic" 5` → cap=5. `/regressing "topic" 3명` → agents=3, cap=10. **User interaction:** Silence = proceed with recommended parameters. User may adjust any parameter before execution begins. ### Step 2.6: Goal-Mode Handoff (host continuation) Session continuation is goal-driven, not hook-forced. The host's goal mode (Claude Code 2.1.139+ `/goal`, Codex CLI 0.128.0+ `/goal`) keeps the session working until the host's evaluator confirms the Discussion is concluded. The old unconditional Stop-hook block (`regressing-loop-guard.js`) is retired; `completion-controller.js` still enforces bounded continuation on execution-authorized turns. Immediately after Step 2.5, print this ready-to-paste line for the user (fill in the real D-ID, file name, and cap): ``` /goal Crabshell regressing {D-ID}: every item under "## Convergence Criteria" in .crabshell/discussion/{D-file}.md is met and its frontmatter status is "concluded", or the D Final Report records the cycle cap {N} as reached. Judge only by reading that document. ``` - Starting goal mode is the user's choice; the skill cannot start it. If the user does not start it, cycles still continue autonomously per Rule 5. - The goal condition MUST point at the D document only — the evaluator judges by reading it, so cycle results must land in the D/P/T documents (document-first) for the evaluator to see progress. ### Step 3: Pre-check (optional) - Check if related Investigation (I) documents exist - I is independent — may or may not be included, at discretion - I is pre-work outside the cycle loop ### Step 4: Cycle Loop ``` repeat until convergence or cap reached: Step 4a: Planning (P) Step 4b: Ticketing (T) Step 4c: Ticket Execution Step 4d: Feedback Transfer ``` #### Step 4a: Planning — Create P(n) - Invoke `/planning`, formulate plan based on D's IA - **Cycle 1**: Plan addresses the highest-impact improvements for the CURRENT state. MUST NOT pre-allocate or partition work across future cycles. Plan should be completable in this single cycle. - **Cycle 2+**: P(n) Context MUST include T(n-1)'s `## Final Verification > Next Direction`. Plan MUST directly respond to diagnosed problems from the previous cycle — not continue a pre-determined schedule. - Parent: inspect the authoritative references, formulate the plan, and append analysis to the P document. - Optional delegation/review: use only for bounded independent work or a material risk. A reviewer, when used, checks the plan without receiving prior conclusions as its evidence source. - Parent: intent check against D's IA. REJECT plans that pre-allocate future-cycle work, reopen decisive references, and append the final intent check to the P document. - **Quality Gate (BLOCKING):** Parent analysis and Intent Check MUST be populated before Step 4b. If optional review was used, its evidence and the parent's disposition of each finding MUST also be recorded. An agent count or an empty optional-review section is not a quality gate. - After approval, proceed to ticket creation After /planning completes, update regressing state: - Set `"planId": "{P-ID}"`, `"lastUpdatedAt": "{ISO}"` using: `"{NODE_PATH}" -e "const f='{PROJECT_DIR}/.crabshell/memory/regressing-state.json';const s=JSON.parse(require('fs').readFileSync(f,'utf8'));s.planId='{P-ID}';s.lastUpdatedAt=new Date().toISOString();require('fs').writeFileSync(f,JSON.stringify(s,null,2))"` (phase transition is automatic via PostToolUse hook) #### Step 4b: Ticketing — Create T(n,1..M) - Invoke `/ticketing` one or more times per plan to create tickets from P(n) - Ticket sizing: 3-5 acceptance criteria per ticket. Independent work items are separate tickets. - A plan with a single coherent work item produces one ticket. A plan with multiple independent work items produces multiple tickets. After each /ticketing invocation, update regressing state: - Append the new ticket's ID to `"ticketIds"` array, update `"lastUpdatedAt": "{ISO}"` using: `"{NODE_PATH}" -e "const f='{PROJECT_DIR}/.crabshell/memory/regressing-state.json';const s=JSON.parse(require('fs').readFileSync(f,'utf8'));s.ticketIds.push('{T-ID}');s.lastUpdatedAt=new Date().toISOString();require('fs').writeFileSync(f,JSON.stringify(s,null,2))"` (phase transition is automatic via PostToolUse hook) #### Step 4c: Ticket Execution - Execute each T(n,m) using ticketing's parent-owned execution and verification flow. - Each ticket is an independent execution cycle - **Ticket execution ordering:** Dependent tickets (e.g., T002 depends on T001's file changes) MUST execute sequentially — T001 completes before T002 starts. Independent tickets MAY execute in parallel. The Orchestrator determines dependency order before execution begins. - **Agent flow:** The parent owns each phase and delegates only bounded independent work when risk or latency justifies it. No worker count or WA:RA pairing is a completion condition. - Parent executes in-scope work and appends execution evidence to the T document. Delegation is optional and bounded by the ticket contract. - **Framing:** Any delegated prompt follows ticketing/planning framing and verification standards, names exact scope and non-goals, and forbids fan-out. - Optional independent review: use when change risk, shared contracts, security, data loss, or user-visible behavior warrants it. Reviewer count never follows worker count. - **Independence Protocol:** A reviewer MUST NOT use worker conclusions as its observation source. Provide the ticket acceptance/verification contract and the P/O/G template; the parent later cross-references findings against implementation evidence. - **Reviewer prompt, when review is used, MUST include this verification context and output template:** ``` Verification = closing the gap between belief and reality through observation. Fill Prediction BEFORE looking at the code. Fill Observation ONLY from tool output. The Gap column is where real findings live — if Gap is always "none", you are confirming, not verifying. For each verification item, provide ALL fields: | Item | Type | Prediction (before observation) | Observation (tool output required) | Gap | |------|------|-------------------------------|-----------------------------------|-----| Type: `behavioral` = runtime execution observed (ran command, triggered feature, checked output) Type: `structural` = static check (grep, file read, code inspection) Rules: - Observation MUST include tool output (Bash execution, Read result, diff, etc.) - If Prediction and Observation are identical text → INVALID (no actual observation occurred) - If direct execution is impossible: state "Indirect: {method}" + why direct is impossible - Empty Observation or Gap fields → entire verification is INVALID ``` - **Verification Tool Check (BEFORE Orchestrator evaluation):** 1. Check if `.crabshell/verification/manifest.json` exists 2. If YES → `/verifying run` and include results in evaluation 3. If NO → `/verifying` to create manifest, then `/verifying run` 4. No executable runtime → skip with note - Parent: final verification → append to T document. MUST critically evaluate implementation evidence and any optional review. Default posture: skepticism — "ALL PASS" requires more justification than "FAIL". A worker/reviewer claim is never the completion condition. - Correctness: Was it done correctly? Cite specific evidence (command output, observed behavior). - Coherence: Do the changes from this cycle work together as a whole? Individual items may each pass, but combined output may have integration gaps. Verify that parts form a coherent whole, not just that each passes individually. **Coherence verification methods (minimum 2 of the following):** - **Cross-file sync check:** When the same concept appears in multiple files, grep for the concept in all locations and confirm consistent wording/semantics. - **Reference integrity:** When file A references file B's content, verify the reference target actually exists and matches. - **Integration test:** Run the changed code/hook and verify that outputs from multiple changed files interact correctly. - **Contradiction scan:** Explicitly check whether any two changes give contradictory instructions. - **Pipeline contradiction scan:** Check whether this change contradicts logic in related pipelines. Level 1: within the changed files. Level 2: in files that interact with the changed component (imports, callers, shared state). Level 3: against project rules/philosophy (CLAUDE.md, SKILL.md principles). A change that works locally but contradicts a related pipeline is not coherent. "Coherent" or "일관됨" as a one-line verdict without executing any of the above methods is INVALID. - Improvement Opportunities: What gaps remain? What was attempted but didn't work well? (Orchestrator MUST enumerate what was examined. "No improvements" requires detailed justification of what was checked and why no improvements apply — minimum 3 sentences referencing specific aspects.) - **Evidence Gate (BLOCKING — check BEFORE evaluating content):** Agents can generate text that looks like verification without actual observation. Apply this gate to parent and delegated evidence alike. □ Does each verification item have Prediction, Observation, AND Gap fields? □ Does Observation contain tool output evidence? (for directly-executable items) □ Is Prediction ≠ Observation? (copy detection) □ For indirect verification: is the reason stated? □ Does at least 1 verification item have Type = behavioral? (structural-only = insufficient for runtime features) → If ANY check fails: reject that evidence and re-run the observation. - **Independent Evidence Cross-Reference (when delegation/review was used):** Compare independent findings against implementation evidence. 1. Read the independent P/O/G findings 2. Read the execution results and direct tool output 3. Identify discrepancies — items where independent observation found problems implementation evidence did not report, or where implementation claimed success but direct observation found issues 4. Discrepancies are the highest-priority findings and must be addressed in Correctness evaluation - Next Direction (while verification finds gaps and cycle < cap; final cycle uses Final Report instead): - **Problems Found**: Specific problems or shortcomings observed in THIS cycle's output, with evidence. - **Root Cause Hypothesis**: Why did these problems occur? - **Recommended Focus**: What should the next cycle prioritize and why? - (If this section reads like a generic TODO list without referencing specific observations from this cycle, it is INVALID — rewrite with evidence.) After ticket execution completes, update regressing state: - Set `"phase": "feedback"`, `"lastUpdatedAt": "{ISO}"` using: `"{NODE_PATH}" -e "const f='{PROJECT_DIR}/.crabshell/memory/regressing-state.json';const s=JSON.parse(require('fs').readFileSync(f,'utf8'));s.phase='feedback';s.lastUpdatedAt=new Date().toISOString();require('fs').writeFileSync(f,JSON.stringify(s,null,2))"` #### Step 4d: Feedback Transfer (Quality Gate) - **Single ticket:** Extract T(n,1)'s `## Final Verification > Next Direction` directly. - **Multiple tickets:** The Orchestrator synthesizes all tickets' `## Final Verification` sections into a unified Next Direction. The synthesis must integrate findings across tickets, not merely concatenate them. - **Quality check before transfer:** The Orchestrator MUST verify the Next Direction (whether extracted or synthesized) contains: (1) Specific problems diagnosed with evidence from this cycle (2) Root cause hypothesis (3) Recommended focus with rationale If Next Direction is a generic TODO list without cycle-specific observations → REJECT and require re-evaluation. - Pass validated feedback to next cycle P(n+1)'s Context - **Document-first rule:** Record the feedback transfer in the D document's Discussion Log and the P(n+1) document's Context section using the Edit tool BEFORE beginning cycle planning. The document update is the primary action; conversation narration is secondary. - This transfer is explicitly performed by the Orchestrator After feedback transfer: - If verification found gaps AND cycle < cap: Set fields using: `"{NODE_PATH}" -e "const f='{PROJECT_DIR}/.crabshell/memory/regressing-state.json';const s=JSON.parse(require('fs').readFileSync(f,'utf8'));s.cycle++;s.phase='planning';s.planId=null;s.ticketIds=[];s.lastUpdatedAt=new Date().toISOString();require('fs').writeFileSync(f,JSON.stringify(s,null,2))"` - **If cycle = cap AND cap was defaulted (not user-specified):** Present a progress report to the user summarizing what was achieved and what gaps remain. User decides: approve another 10 cycles (raises cap) or stop. If approved, update totalCycles: `s.totalCycles = s.cycle + 10`. - If converged (Rule 7) OR cycle = cap (user-specified): proceed to Step 5 ### Step 5: Close Discussion (D) + Final Report After convergence or reaching the cap, return to the D document: 1. Append the Final Report to D's Discussion Log - **Document-first rule:** Write the Final Report to the D document using the Edit tool FIRST. After the document is updated, provide a brief summary to the user. The document update is the primary output; the conversation summary is secondary. 2. Transition D to `concluded` After final report, clean up regressing state: - Delete state file: `"{NODE_PATH}" -e "try{require('fs').unlinkSync('{PROJECT_DIR}/.crabshell/memory/regressing-state.json')}catch(e){}"` Final Report format: ``` ### [{timestamp}] Regressing Final Report Converged after {actual} cycles (cap: {N}) Termination reason: {convergence | cap reached | user stop} **Gap Reduction:** | Cycle | Gaps Identified | Gaps Resolved | Key Improvement | |-------|----------------|---------------|-----------------| | 1 | ... | ... | ... | | ... | ... | ... | ... | **Improvement Trajectory:** - Cycle 1→2: {key changes} - Cycle 2→3: {key changes} **Final State:** - Achieved: ... - Remaining gaps: ... - Future recommendations: ... ``` ## Document Structure One D wraps the entire session. Each cycle creates one P + one or more T: ``` D (open) → P(1) → T(1,1), T(1,2), ... [cycle 1] → P(2) → T(2,1) [cycle 2] → ... → P(N) → T(N,1), T(N,2), ... [cycle N] D (closed with final report) ``` | Document | Count | Role | |----------|-------|------| | D | 1 | Top-level container: intent, IA, final report | | P | N | One per cycle: plan based on D's IA + previous feedback | | T | >= N | One or more per cycle: execution + verification | ## User Interaction - **At start**: Confirm topic. Cap is 10 unless user explicitly wrote a number. Do not infer cap from context, memory, or past sessions. Print the goal-mode handoff line (Step 2.6) so the user can run the session under host goal mode. - **During**: Fully autonomous. Terminates on convergence (Rule 7) or when cap is reached. At every 10-cycle boundary (when cap was defaulted), present progress report — user approves raising cap by 10 or stops. - **At end**: Present final report in D → user requests raising cap or terminates ## Rules 1. **1 cycle = 1 P + 1..M T.** Each cycle produces exactly one plan and one or more tickets. Ticket sizing: 3-5 acceptance criteria per ticket, independent work items are separate tickets. No steps may be skipped. 2. **One D wraps all cycles.** D opens at start, closes with final report at end. Do NOT create a new D per cycle. 3. **Verification-based Optimization.** No iteration without verification. Must verify at the end of each cycle, and verification results determine the next cycle. 4. **T→P context transfer is mandatory.** The Orchestrator must explicitly pass T(n)'s final verification results as Context to P(n+1). 5. **User intervention only at the end.** Do not ask for user confirmation during intermediate cycles. 6. **Use existing skill invocations.** Invoke discussing (once at start), planning, and ticketing skills internally. 7. **Early termination on convergence.** If the Orchestrator's verification finds no improvement opportunities with substantive justification (minimum 3 sentences enumerating what was examined and why further cycles would not improve the result), the session terminates early. Generic "ALL PASS" without this justification is not valid convergence — it is rubber-stamping. **When the wrapping D document contains a `## Convergence Criteria` section, the Orchestrator MUST evaluate each criterion explicitly — convergence is only valid when all listed criteria are met or explicitly declared out-of-scope with rationale.** 8. **Hotfix is the lightweight alternative.** Regressing is the primary mode; standalone one-off tasks are done directly and recorded with hotfix. 9. **D's IA is the constant anchor.** All P and T documents reference D's IA as read-only evaluation criteria throughout all cycles. 10. **Parent-owned orchestration.** The parent owns intent, implementation decisions, decisive verification, and completion. Delegate only bounded independent work when risk or latency justifies it; do not require a worker/reviewer pair or use agent count as evidence. Delegates do not fan out. 11. **Orchestrator anti-rubber-stamp.** The Orchestrator MUST provide substantive evaluation for each cycle. "No improvement opportunities" and "ALL PASS" without detailed justification are INVALID. When the Orchestrator genuinely finds no improvements, it must enumerate what was specifically examined and provide a reasoned argument (minimum 3 sentences) for why the output is optimal. 12. **Cycles are for result improvement, not sequential work progression.** Each cycle produces a complete result and verifies it. The next cycle's purpose is to improve the previous cycle's output based on verified gaps — not to continue with remaining work. P(1) MUST NOT pre-allocate work across cycles. If P(n) divides total work into equal parts or references "what cycle N+1 will do," it is INVALID. The scope of cycle N+1 is unknown until cycle N's verification reveals what needs improvement. Cycle count is emergent — N is a safety cap, not a quota to fill. **Sequential tasks (version bump, cache sync, deploy) belong in the SAME cycle as the code change, as separate tickets — NOT as separate cycles.** A cycle is incomplete if it produces a code change without its operational follow-through. 13. **Distinct-risk review.** When multiple reviewers are useful, assign different risks rather than duplicating a checklist. The parent compares their independent evidence and resolves discrepancies; no reviewer count or cross-review ritual is a completion condition. 14. **Question-save-continue protocol.** When a question arises during ticket execution that would normally pause for user input: (1) Do NOT emit the question to the user. (2) Append the question as an `## Open Questions` entry to the active T document using Edit tool (document-first). Include: question text, local timestamp, context (which AC triggered the question). (3) Make a reasonable assumption to unblock execution — state the assumption in the T document entry. (4) Continue execution without waiting. Open questions are addressed by the next cycle's planning phase. Exception: questions about destructive actions (delete, reset, overwrite) MAY be emitted to the user — state the specific risk first.