refine

Files (5)

• SKILL.md
• refine_output.ncl
• refine_output_apply.ncl
• refine_procedure.ncl
• sync_sketch.py · scripts/

SKILL.md (first lines)

# REFINE Protocol v1.0: Contraction Mapping & Fixed-Point Convergence

**Absorb → Audit → Iterate → Sweep → Report**

This workflow defines the `/refine` execution loop. The objective is to guide sequence token generation through a series of discrete state transitions (Absorb, Audit, Iterate, Sweep, Report) to systematically reduce the entropy of pre-existing artifacts. The process is modeled as an iterative contraction mapping that halts only when a stable fixed point is verified.

---

## Philosophy & Mathematical Model

Refining an existing artifact is modeled as finding the unique fixed point $\mathbf{S}^*$ of a state-space contraction mapping. Let $\mathcal{X}$ be the space of artifact configurations, and let $d: \mathcal{X} \times \mathcal{X} \rightarrow \mathbb{R}_{\ge 0}$ be a metric proportional to the residual entropy and count of latent/active flaws. The refinement operator $R: \mathcal{X} \rightarrow \mathcal{X}$ is a contraction if:

$$d(R(\mathbf{A}), R(\mathbf{B})) \le q \cdot d(\mathbf{A}, \mathbf{B})$$

for all $\mathbf{A}, \mathbf{B} \in \mathcal{X}$ and some contraction factor $0 \le q < 1$. By the Banach Fixed-Point Theorem, repeated application of $R$ converges to the unique fixed point:

$$\mathbf{S}^* = \lim_{k \rightarrow \infty} R^k(\mathbf{S}_0)$$

### CyberCorrect & Computable Loop Dynamics
To evaluate convergence in real-time, the error metric $e_k$ is computed using a **computable proxy metric** $d_p(\mathbf{S}_k)$, defined as the count of unresolved (`PENDING` or `IN_PROGRESS`) items in `REF_LEDGER`. The convergence rate is defined as:

$$\rho_k = \frac{d_p(\mathbf{S}_k)}{d_p(\mathbf{S}_{k-1})}$$

For a true contraction, $\rho_k \le q < 1$. If $d_p(\mathbf{S}_k) \to 0$, the system is Cauchy-convergent. In practical autoregressive generations:
1. **Unstable Oscillations (Limit Cycles):** If $\rho_k \ge 1$ (active only when $d_p(\mathbf{S}_{k-1}) > 0$ and $d_p(\mathbf{S}_k) > 0$) or if codebase states exhibit exact tracked workspace file hash equality with any prior loop state ($\mathbf{S}_k = \mathbf{S}_j$ for $0 \le j < k$ stored in `TRACKED_WORKSPACE_HASHES`), the loop has entered an unstable cycle. The system must adapt search parameters (lower generation temperature, inject explicit negative examples, or alter subagent critique rubrics) or execute the rollback protocol to break the attractor basin.
2. **Diminishing Returns & Stochastic Cascades:** Self-correction exhibits sublinear convergence, where functional errors are corrected early, but sequential, identical sweeps on unchanged code accumulate stochastic LLM noise (false positive critiques). To prevent these cascades, sweep angles must execute in parallel, and any new subagent finding on unchanged code must be ignored unless backed by a deterministic test or static linter failure.

### Prefix-Induced Attractor Basin Bias
Autoregressive Large Language Models do not generate tokens in a vacuum; they traverse a sequence probability landscape where each token step is conditioned on the historical prefix $\mathbf{S}_t$. When the same agent that modified the code also reviews it, the prefix $\mathbf{S}_t$ contains the refiner's internal steps, design rationale, and implicit assumptions. This warps the landscape to construct a deep **attractor basin** around the refiner's localized choices, mathematically biasing the walk to reinforce its own decisions.

To break this self-congratulatory lock-in and achieve a non-delusional fixed point $\mathbf{S}^*$, validation must execute under **Multi-Boundary Subagent Sweeps (MBSS)**. We project the artifact's state space onto orthogonal axes of critique using independent subagents primed with distinct Initial Boundary Conditions (IBCs) that are completely blind to the refiner's internal trajectory history and to each other's active rubrics or findings, preventing any collusive context leakage.

### The Refine/Review Dialectic: Constructive Tension
Refinement is not a process of compliance-driven submission; it is a collaborative, asynchronous synthesis between two expert viewpoints with a single shared goal: **offering a genuinely compelling improvement to the codebase that is worth maintaining.**

This process rests on a dialectical balance between the refiner (worker) and the reviewers (maintainers) who operate using opposite methods but a unified purpose:
1. **Instructing Agents as World-Class Experts:** Neither the refiner nor the maintainer reviewers are limited in capability. They are world-class experts who have absolute confidence in their respective domains, but possess the humility to concede and adapt when a superior design, cleaner implementation, or stronger evidence-backed argument is offered. They are the best at what they do and act with confidence and mutual respect.
2. **Defending Choices vs. Resubmitting Bias (The Worker's Stand):** Maintainers, by their nature, conduct myopic reviews constrained to their specific rubrics (e.g., modular coupling, allocation count, naming conventions). The refiner, holding the macro context, may see a cohesive piece of the puzzle that the subagents and reviewers missed. In such moments, the refiner must **take a stand** and defend its design choices. It must resist submissive over-engineering or compliant "fixes" that compromise the overall goal. However, just as crucially, the worker **cannot resubmit its own bias** back into the equation after that bias has been deferred or challenged. It must remain objective and humble.
3. **Meticulous Note-Keeping for Self-Preservation:** To keep the higher-level goal on track in long sessions and ensure the worker itself cannot forget what has occurred during refinement, the worker is coached and structurally required to take **meticulous progress notes** in the active sketch file. The sketch is the refiner's memory; it guards against context loss, prevents prefix-induced self-bias from creeping back into justifications, and documents why specific design choices were defended.
4. **Humility to Leverage Reviewer Experience:** The maintainers have deep experience and know their codebase's motivation better than anyone. They do not accept lazy hacks or "BS" code. They want help solving problems, and their experience is invaluable to raising code and documentation to the repository's highest standards. The refiner must recognize when maintainer feedback is a genuine avenue for improvement and concede when a better path is offered.
5. **API Stability and Project Objectives:** High-level project objectives and API stability override individual nits. Once API stability is reached, compromises must be made to preserve the public API surface. Prioritizing API stability before a release/milestone is reached is premature and counterproductive; design soundness takes precedence early on.

### The Accuracy-Correction Paradox (SCoRe Trajectory Guardrails)
To prevent the system from degrading correct artifacts or entering overcorrection loops, we enforce strict **Deterministic Grounding**:
- **Verifier Grounding:** Any critique, issue, or ledger item generated by a subagent MUST be rejected unless it can be mapped directly to a deterministic evaluator failure (such as a linter warning, a failed test execution, a syntax error, or a documented spec violation). Reject any subagent finding that does not include a stdout/stderr trace or specific file/line location. Purely subjective or stylistic criticisms are banned from the ledger (see Prime Directive 4).
- **Socratic Verification Gate:** Socratic checks (e.g., assessing code elegance) may guide human-in-the-loop iterations but cannot spawn ledger entries unless they are converted into concrete, reproducible test assertions or compiler checks.
- **Sieving & Cutting Pruning Invariant:** Counter the additive bias of self-correction loops. The agent MUST actively evaluate and prune superfluous structures, redundant variables, comments, or dependencies introduced in follow-up iterations that no longer serve the target goal (see Section 3 for procedural details).
- **Regression Invariance:** Every iteration step must verify that previous working test suites continue to pass. If a change breaks a regression test, the edit is immediately discarded, the state rolled back, and the correction re-attempted.
- **Git History Invariance:** The use of history-altering git commands is strictly prohibited. All history must remain linear and immutable (see Prime Directive 9).
- **Core Premise Verification (The "Turd-Polishing" Guardrail):** Before optimizing or polishing any target artifact, the agent must challenge the underlying design. If a core premise is found to be flawed, the agent MUST log the premise failure in the sketch and transition to `HALT` (see Section 3 for procedural details).

### Loop Bounds and Exit Metrics
To ensure sequence generations converge to $\mathbf{S}^*$ rather than terminating in local sub-optimal minima, the workflow enforces three control-theoretic bounds that scale dynamically based on the complexity of the task (assessed during `ABSORB`):

1. **Minimum Execution Loops ($N_{min}$):** The loop MUST execute at least $N_{min}$ iterations, even if no issues are initially visible.
   *Convergence Shortcut:* If the initial audit finds $d_p(\mathbf{S}_0) = 0$ and the first parallel sweep phase yields zero findings, the artifact is declared converged, and the system bypasses $N_{min}$ to transition directly to `REPORT`.
   > [!IMPORTANT]
   > The Convergence Shortcut still requires executing the full `SWEEP` phase. The refiner MUST spawn the independent subagents to verify there are zero findings. Transitioning directly to `REPORT` from `AUDIT` without running the sweep is a protocol violation.
2. **Consecutive Clean Sweeps ($M_{sweep}$):** Once the active refinement ledger is empty, the agent must perform $M_{sweep}$ consecutive adversarial sweeps.
3. **Divergence Boundary ($K_{max}$):** To prevent infinite limit cycles or chaotic oscillations, we define a loop limit $K_{max}$.

The exact parameter bounds are initialized in the `ABSORB` phase based on task complexity (see Section 1). Only when $M_{sweep}$ consecutive sweeps find zero new issues on the final, static codebase state can the system declare convergence ($R(\mathbf{S}^*) = \mathbf{S}^*$) and proceed to the `REPORT` phase. Transitioning to `REPORT` directly from `ITERATE` or `AUDIT` is strictly prohibited. Any code modification resets `CONSECUTIVE_CLEAN_SWEEPS` to `0`, requiring a full reset of the sweep phase.

---

## Scope

> [!IMPORTANT]
> `/refine` is for **optimizing and polishing pre-existing artifacts**. It is NOT for implementing new features (that's `/core`) nor for drafting high-level architecture; that strategic work is governed by the [Planning Invariants](../../ambient.md#planning-invariants), not this loop. If the sequence begins adding new functional scopes or diverging from the initial target artifact, the walk must halt and return control to the human.

---

## Grammar

```yaml
# 1. METADATA
TOPIC: "topic-slug"            # Topic slug for the refinement session
STATUS: [ABSORB | CLARIFY | AUDIT | ITERATE | SWEEP | REVIEW | REPORT | HALT]

# 2. CONTEXT
CTX:
  TARGET_ARTIFACTS:
    - "path/to/target/file"
  TEST_FILES:
    - "path/to/test/file"
  SPECIFICATION_FILES:
    - "path/to/specification/file"
  ARCHITECTURAL_DOCS:
    - "path/to/architectural/doc"   # Mapped architectural docs (README, ADR, etc.)
  GOAL: "Verbatim objective statement"
  MODE: [INTERACTIVE | AUTONOMOUS]  # Interactive requires human gates; Autonomous runs under /goal
  PREMISE_BYPASS: [TRUE | FALSE]     # If TRUE, bypass premise verification halts (defaults to FALSE)
  WORKTREE_PATH: "path/to/worktree"  # Path to the isolated git worktree
  AGENT_BRANCH: "branch_name"        # Current active agent branch attempt (e.g., agent/refine-<topic>-attempt-1)
  ASSUMPTIONS: []            # Hypotheses logged during autonomous CLARIFY resolution
  CONSTRAINTS:
    N_MIN: 4                 # Adaptive loop limit scaled to task complexity
    M_SWEEP: 4               # Adaptive sweep limit scaled to task complexity
    K_MAX: 12                # Adaptive divergence boundary
    REVIEW_BUDGET: 3         # Max maintainer review cycles before halting
    SIBLING_SKILLS:          # Sibling skills loaded and consulted during audit
      - robust-testing
      - engineering
      - prior-art

# 3. DYNAMIC REFINEMENT LEDGER
# Track all optimization targets identified during AUDIT or SWEEP phases.
# All items must be RESOLVED before entering the final SWEEP validation gates.
REF_LEDGER:
  - ID: R1
    AXIS: [CORRECTNESS | API_SUFFICIENCY | COMPLIANCE | EDGE_CASES]
    TARGET: "symbol_or_line_or_file"
    STATEMENT: "Description of the target improvement"
    STATUS: [PENDING | IN_PROGRESS | RESOLVED]
    EVIDENCE: "Verification results / test run outputs"

# 4. DYNAMIC REVIEW LEDGER (PR REVIEW)
# Track all nitpicks and design critique targets identified during the REVIEW phase.
# All items must be RESOLVED before human sign-off and merge.

From nrdxp/predicate, MIT.

More from nrdxp/predicate