patpat-loop

Files (52)

• SKILL.md
• openai.yaml · agents/
• architecture-change.md · playbooks/
• arena.md · playbooks/
• authorized-delivery.md · playbooks/
• automation-design.md · playbooks/
• autopilot.md · playbooks/
• behavior-preserving-refactor.md · playbooks/
• behavioral-eval.md · playbooks/
• bespoke-workflow.md · playbooks/
• blast-radius.md · playbooks/
• bounded-change.md · playbooks/
• default-delivery.md · playbooks/
• defect.md · playbooks/
• independent-review.md · playbooks/
• investigation.md · playbooks/
• issue-loop.md · playbooks/
• learning.md · playbooks/
• metric-hillclimb.md · playbooks/
• multi-phase-run.md · playbooks/
• pause-safely.md · playbooks/
• performance.md · playbooks/
• pr-drive.md · playbooks/
• pr-handoff.md · playbooks/
• project-verifier.md · playbooks/
• prototype.md · playbooks/
• rationale-forensics.md · playbooks/
• regression-first.md · playbooks/
• runtime-forensics.md · playbooks/
• session-takeover.md · playbooks/
• skill-change.md · playbooks/
• swarm.md · playbooks/
• trace-forensics.md · playbooks/
• visual-equivalence.md · playbooks/
• worktree-cleanup.md · playbooks/
• boundary-discipline.md · principles/
• earned-parallelism.md · principles/
• encode-lessons.md · principles/
• explain-the-number.md · principles/
• fix-root-causes.md · principles/
• idempotent-effects.md · principles/
• preserve-safety.md · principles/
• proof-over-proxy.md · principles/
• repository-truth.md · principles/
• sequence-verifiable-units.md · principles/
• shape-before-logic.md · principles/
• smallest-safe-change.md · principles/
• benchmark-checklist.md · references/
• earned-representation.md · references/
• execution-graph.md · references/
• operating-protocol.md · references/
• route-catalog.md · references/

SKILL.md (first lines)

# Patpat Loop

Before following this skill, apply the [skill state and mutation gate](references/operating-protocol.md#skill-state-and-mutation-gate).

[`/patpat`](../patpat/SKILL.md) and `/patpat-loop` are the same entry point. Codex uses `$patpat` or `$patpat-loop`.

Patpat is one system. The [operating protocol](references/operating-protocol.md) is the spine: judgment, safety, git, and evidence. Playbooks and principles specialize the work without overriding that spine.

This mode stays on across later turns after explicit invocation. Trusted host hooks may persist it across resume and compaction. Without a host-observed receipt, apply it only for the current session and report `current-turn-only` after a restart. Say `disable /patpat` to opt out. Do not infer activation from a task that merely resembles a playbook.

For non-engineering work, follow [general task judgment](references/general-task-judgment.md) with applicable domain skills. If the task does not affect an engineering or repository boundary, complete and report that work without entering the engineering routing, Git delivery, or durable engineering graph below; the current directory alone does not determine the task type. For mixed work, apply general task judgment to each relevant deliverable and the engineering routes and gates below to every affected engineering or repository boundary. A media file in a repository still needs media-specific verification; its repository mutation also retains repository proof and safety gates.

## Start

Classify the task first from signals: reversibility, uncertainty, blast radius, auth, security, billing, secrets, architecture, cross-cutting, duration, delivery intent, and parallelism need. First activation is context, not a risk signal. First activation alone must not force a full protocol read.

Scale start from that classification:

| Internal routing shape | Positive signals | Execution |
| --- | --- | --- |
| 0, fast-track | One clearly scoped, reversible, non-behavioral artifact; no contract, runtime, security, permission, migration, or delivery effect | Begin with the cheapest useful observation. Read only the matched playbook and principles. Make the bounded change and run the narrowest authoritative static check. Do not open a mandatory todo list or require a numbered checklist. |
| 1, bounded | Clear localized behavior or defect with a small understood caller set and no high-risk boundary | Use the matched change or debug route, the 5-field proof contract, and targeted behavioral verification. |
| 2, design-gated | Any ambiguity, architecture, schema, migration, public contract, auth, security, billing, secret, cross-cutting behavior, or unresolved multi-step dependency | Resolve the design boundary through `patpat-architect`; use fuller protocol and verification checkpoints before mutation. Use `patpat-run` when the work is durable, dependent, or resumable. |

These are internal routing shapes, not user-selectable modes. File count is weak evidence after callers and contracts are inspected: one security-sensitive file is design-gated, while several independent prose-only files may remain fast-track. Any Tier 2 signal overrides lower-tier hints. A clear delivery or other external effect uses its existing specialist route and fuller authority gates; externality alone does not imply `patpat-architect`. Mutating work in every shape still defines the 5-field proof contract before editing and verifies on the authoritative surface.

Inspect, execute, or measure before asking. Ask only for product preference, authority, a destructive action, security, or another human-only choice. Do not expose named user-selectable modes.

## Principle index

Read the linked file when the trigger fires. Cite a principle only when it changed a decision, using the lightweight decision format: `[Principle Name] -> [Concrete decision or architectural choice made based on it]`. Do not name-drop principles without an altered choice.

- [Repository truth](principles/repository-truth.md) before deciding. Inspect live evidence. Do not prefer assumptions.
- [Smallest safe change](principles/smallest-safe-change.md) when sizing a diff. Delete, reuse, then patch. Keep comments only for constraints the code cannot show.
- [Shape before logic](principles/shape-before-logic.md) before writing behavior. Name legal states first. Make illegal combinations unrepresentable.
- [Boundary discipline](principles/boundary-discipline.md) at CLI, config, network, and auth edges. Guard the boundary. Trust internal types.
- [Preserve safety](principles/preserve-safety.md) on any auth, permission, billing, secret, or destructive path. Simplicity must not weaken a gate.
- [Proof over proxy](principles/proof-over-proxy.md) before claiming done. Observe the authoritative surface, including the real subject path for tests and evaluators.
- [Explain the number](principles/explain-the-number.md) before trusting a metric. Name the limiter and rule out proxy artifacts.
- [Fix root causes](principles/fix-root-causes.md) on defects. Reproduce when safe and practical; otherwise trace without triggering harm. Do not silence a crash with a nil check. After two fixes sharing one premise fail the same gate, write and test that premise before adding another fix.
- [Sequence verifiable units](principles/sequence-verifiable-units.md) on multi-step work. A verifiable unit is not a throwaway compatibility layer. Build a rerunnable tool after the first proven manual unit.
- [Idempotent effects](principles/idempotent-effects.md) on retries, installs, and lifecycle steps.
- [Encode lessons](principles/encode-lessons.md) only for recurring failures, at the earliest enforceable boundary.
- [Earned parallelism](principles/earned-parallelism.md) before any writable fan-out. Default to one owner.
- [Subtract before you add](principles/subtract-before-you-add.md) before expanding footprint. Delete, simplify, or refactor existing paths before introducing new files or abstractions.
- [Experience first](principles/experience-first.md) when designing interactions. Shape contracts, errors, and CLI ergonomics around the consumer, not internal convenience.
- [Minimize reader load](principles/minimize-reader-load.md) on code and diffs. Keep control flow linear, names domain-accurate, and structural indirection minimal.
- [Guard the context window](principles/guard-the-context-window.md) across tool calls. Filter and compact evidence at the source; never dump raw, noisy logs into context.
- [Attack the premise](principles/attack-the-premise.md) when complexity cascades. Question upstream assumptions before nursing brittle workarounds.
- [Redesign from first principles](principles/redesign-from-first-principles.md) when constraints choke progress. Rebuild the essential invariant cleanly from platform primitives.

## Route the work

Before executing a specialist workflow, resolve its `metadata.patpat.ontology` against current evidence. Check required states, use only a unique eligible producer inside the user's authorized scope, preserve the mutation and approval gates, and verify any produced state. The [operating protocol](references/operating-protocol.md#skill-state-and-mutation-gate) defines the gate. Metadata is routing evidence, not authority.

Orchestrate through composition rather than duplication: `patpat-loop` coordinates workflow transitions and delegates to specialized skills (`patpat-architect`, `patpat-change`, `patpat-engineer`, `patpat-verify`, `patpat-review`, `patpat-unslop`, `patpat-ship`) rather than absorbing their logic into a monolithic God Skill. Specialist skills configured with `disable-model-invocation: true` are shielded from ambient host auto-triggering but remain composable within an active Patpat session.

The user speaks plainly and invokes `/patpat` (or host equivalent). Select the route for the earliest unresolved decision found during inspection; an implementation request does not settle an undefined requirement or contract. Use the 8 existing primary routes:

| Intent | Route | Primary Skill | Playbook Reference |
| --- | --- | --- | --- |
| Read-only question, audit, repository understanding, or diagnosis-only defect | `inspect` | [`patpat-inspect`](../patpat-inspect/SKILL.md) | [Investigation](playbooks/investigation.md) |
| Defective or unexplained behavior with implementation requested | `debug` | [`patpat-debug`](../patpat-debug/SKILL.md) | [Defect](playbooks/defect.md) |
| Bounded feature or localized modification | `change` | [`patpat-change`](../patpat-change/SKILL.md) | [Bounded change](playbooks/bounded-change.md) |
| Contract, architecture, migration, security-sensitive, or cross-cutting design | `architect` | [`patpat-architect`](../patpat-architect/SKILL.md) | [Architecture change](playbooks/architecture-change.md) |
| Proof of an existing claim or authoritative artifact | `verify` | [`patpat-verify`](../patpat-verify/SKILL.md) | Use the workflow directly |
| Independent challenge of an implementation, diff, or proof claim | `review` | [`patpat-review`](../patpat-review/SKILL.md) | [Independent review](playbooks/independent-review.md) |
| Named commit, PR update, publish, or authorized deploy | `ship` | [`patpat-ship`](../patpat-ship/SKILL.md) | [Authorized delivery](playbooks/authorized-delivery.md) |
| Durable multi-phase execution, implementation or coordination across a PR queue/stack, or overnight run | `run` | [`patpat-run`](../patpat-run/SKILL.md) | [Multi-phase run](playbooks/multi-phase-run.md) |

Consult the [route catalog](references/route-catalog.md) for specialized workflows (`arena`, `swarm`, `automation`, `eval`, `formal verification`, `perf`, `learn`, explicit game-building requests, and idea, plan, or codebase diagram requests) or overlap. If no narrow route fits, use `patpat-architect` or `patpat-run`.

## Run the graph

Read the matched workflow and relevant references. Read [the execution graph](references/execution-graph.md) for fuller or durable work and when failed evidence requires a return edge. Reuse unchanged instructions already loaded in this session.

```text
FRAME -> INSPECT -> PROOF CONTRACT -> ACT -> VERIFY
In FRAME, perform In-Your-Own-Words Digestion before acting: articulate (1) Core Objective, (2) Non-negotiables, and (3) Acceptance Criteria in plain, concise terms to establish explicit alignment.
VERIFY -> REPORT when the edit is local, reversible, and not shipping
VERIFY -> REVIEW before default ship, land or merge, durable-run LEARN or REPORT, and for auth, billing, secrets, architecture, or cross-cutting work
REVIEW -> changes required -> INSPECT / PROOF CONTRACT / ACT -> VERIFY
REVIEW -> LEARN? -> propose and wait for approval -> approved edit -> VERIFY -> REVIEW -> REPORT
REVIEW -> REPORT when no lesson needs encoding
LEARN approval pending -> hold; approval declined -> REPORT without editing
REPORT -> patpat-ship only with delivery intent and fresh verify + review (external; run remains terminal)
LAND? -> MERGE a green reviewed PR only with explicit land or merge
```

A proof contract names Claim, Surface, Action, Expect, and Cleanup. Cover material requirements using [proof over proxy](principles/proof-over-proxy.md). Independent review remains required before default ship, land or merge, durable-run LEARN or REPORT, and for auth, billing, secrets, architecture, or cross-cutting work. Focused verify without independent review is allowed only for non-shipping local reversible edits.

When evidence fails, classify it as an implementation defect, verifier defect, or environment blocker. Return to the earliest invalid state and follow the [bounded retry and Diagnostic Delta contract](references/execution-graph.md#bounded-retry-and-diagnostic-delta). After three consecutive failures from the same unresolved blocker, stop and name the evidence required to continue. In durable runs, the blocker key, failure class, and graph node define the streak; a changed snapshot alone does not clear it.

Enter `LEARN?` only for a recurring failure worth encoding.

## Preserve control

- Ordinary in-scope edits proceed under `/patpat` without asking permission to type.
- Explicit `/patpat` or `$patpat` activation authorizes the loop, proof, and verify; it does not by itself force independent review or a PR. [Default delivery](playbooks/default-delivery.md) runs only when delivery intent exists. Higher-priority repository rules and `don't commit` / `local only` still win.
- Overnight, "don't stop", or "going to bed" is delivery intent: continue through verify, review, and commit-and-PR, then stop merge-ready. Never deploy by implication.
- Merge a green verified PR only when the user explicitly names land or merge. Treat ambiguous `ship it` as commit-and-PR, not merge.
- Pause for production deploy, package publish, force-push, data deletion, secret rotation, and risky auth, billing, or permission changes.
- Workers never ship. The parent ships.

## Earn parallelism

Default to one owner. Workers return compact findings and evidence, not transcripts. Arena, swarm, and autopilot run only when [earned parallelism](principles/earned-parallelism.md) passes, and they fall back to serial work when isolation is missing. Give every writable slice a separate Git worktree or host-enforced sandbox with its own Git index and process boundary; disjoint files in one shared worktree are not isolation. Use [`patpat-engineer`](../patpat-engineer/SKILL.md) for isolated slices. The parent verifies the integrated result. Do not trust worker summaries. The parent then runs default delivery when delivery authority exists.

## Report evidence

```text
Changed:
- <observable change and files>

Why:
- <evidence-backed reason>

Verified:
- <verified | partially verified | implemented but not verified | not implemented>: <command or observation>

From goiltpatpat/patpat, MIT.

More from goiltpatpat/patpat