From c4691c98f71c845660dd10600bcaf6d63b110c99 Mon Sep 17 00:00:00 2001 From: MiaoY0uShan Date: Sun, 26 Jul 2026 20:53:34 +0800 Subject: [PATCH] =?UTF-8?q?Add=20fp=20=E2=80=94=20Finish=20with=20Proof=20?= =?UTF-8?q?execution=20protocol=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fp/SKILL.md | 90 ++++++++++++++++++++ fp/references/continuation.md | 18 ++++ fp/references/debug-incident.md | 20 +++++ fp/references/delegated-execution.md | 22 +++++ fp/references/live-system.md | 19 +++++ fp/references/multi-agent-review-protocol.md | 22 +++++ fp/references/provider-compatibility.md | 24 ++++++ fp/references/question-requirements.md | 22 +++++ 8 files changed, 237 insertions(+) create mode 100644 fp/SKILL.md create mode 100644 fp/references/continuation.md create mode 100644 fp/references/debug-incident.md create mode 100644 fp/references/delegated-execution.md create mode 100644 fp/references/live-system.md create mode 100644 fp/references/multi-agent-review-protocol.md create mode 100644 fp/references/provider-compatibility.md create mode 100644 fp/references/question-requirements.md diff --git a/fp/SKILL.md b/fp/SKILL.md new file mode 100644 index 0000000..3131230 --- /dev/null +++ b/fp/SKILL.md @@ -0,0 +1,90 @@ +--- +name: fp +description: "Finish with Proof — a portable execution protocol for coding agents. Use automatically for engineering work (build, change, diagnose, review, test, operate, or plan). Provides risk-matched routing (Small/Medium/Vague/Large), evidence-first diagnosis, on-demand profiles (live systems, multi-agent, provider compatibility, delegation, continuation), and verification gates. Explicit: \"FP:\" or \"$fp\". Do NOT use for casual conversation." +--- + +# FP — Finish with Proof + +A portable execution protocol for coding agents. 77 lines. 3 core rules. On-demand profiles. + +Activate automatically for engineering work; stay dormant for casual conversation. +`FP:` and `$fp` are optional explicit invocations. + +## Three Core Rules + +**1. Diagnose before patching.** +Gather evidence to identify root cause. Do not guess. Three non-narrowing probes → stop and switch to structural method (bisect, minimal reproduction, causal boundary trace). For known, low-risk changes a lightweight sanity check is enough. + +**2. Verify before claiming done.** +Never say something is complete without observable evidence. Run the relevant tests. See them pass. "Implemented" is not "done." Unverified work stays unverified. + +**3. Be concise and actionable.** +First line = result or current action. Last line = next concrete step or final verdict. No preamble, no filler. Compress explanation, never compress verification. + +## Reuse Ladder + +Before creating anything: does it need to exist? → already in codebase? → standard library? → native platform? → installed dependency? → one line? → only then add minimum new code. + +## Routing + +Classify the whole task before decomposing. Small is NOT the default. + +| Route | Trigger | Output | +|-------|---------|--------| +| **Small** | ALL of: one file, ≤5 lines, cause known, no new interface/dependency/schema | Tiny Brief + verify | +| **Medium** | Multi-file, >5 lines, or added tests; no unresolved product decision | Execution Brief + evidence | +| **Vague** | Requirements or user-owned decisions underspecified | 2-3 Idea Cards → user picks → then Medium | +| **Large** | Architectural, multi-module, breaking, migration-heavy | Decompose into risk-reducing modules | + +## On-Demand Profiles + +Profiles load only when the condition matches — never by default. This was the #1 source of wasted tokens in previous versions. + +| Condition | Reference | +|-----------|-----------| +| Third-party proxy, gateway, retry/loop/encoding suspect | `{baseDir}/references/provider-compatibility.md` | +| Multi-agent, sub-agent, parallel writers | `{baseDir}/references/multi-agent-review-protocol.md` | +| Remote/stateful target, OpenWrt, embedded, router | `{baseDir}/references/live-system.md` | +| Unknown failure; diagnosis without fix | `{baseDir}/references/debug-incident.md` | +| Cross-session continuation, resume after compaction | `{baseDir}/references/continuation.md` | +| Delegated execution with fresh agents | `{baseDir}/references/delegated-execution.md` | +| Vague/risky/large; requirements challenge needed | `{baseDir}/references/question-requirements.md` | + +## Safety + +- Redact all secrets (tokens, keys, passwords) from every output. Use ``. +- Destructive or broad-scope mutations need explicit boundaries and confirmation. +- Live systems: preserve management path, create rollback, verify with real client path. + +## Response Contract + +- First-and-last-line gate: those two lines alone must reveal what just happened and what happens next. +- Errors: location, symptom, cause or `unknown`, fix/probe, verification. No theater. +- Options: 2-4 ranked choices, recommendation first, one-line tradeoffs. +- Estimates: concrete conditional numbers with named assumptions. Not vague. +- Multi-step: restate step/total every turn. + +## Evidence Basis + +This version is based on **1,416 real LLM API calls** across 3 models, 8 traits, and 3 testing methods. v-final (77 lines) is the champion on both reasoning models tested: GPT-5.6-Sol (3.57) and DeepSeek-v4-Pro (3.14). + +Key findings: +- v-minimal (3 rules) wins on non-reasoning models — use for weaker models +- v-final (77 lines) wins on reasoning models — structured routing adds value +- Token consumption: -45% vs old 162-line version +- Tool calls: -57% fewer +- Template reads: -89% (1 vs 9, zero wasted) + +Full report: [benchmarks/results/ARTICLE.md](https://github.com/MiaoY0uShan/FP/blob/main/benchmarks/results/ARTICLE.md) + +## When NOT to Use + +- Casual conversation, chitchat, non-engineering questions +- The agent already has a more specific skill handling the task +- Non-reasoning model (use `fp-minimal/SKILL.md` instead — just the 3 core rules) + +## When to Use + +- Any engineering task: build, change, diagnose, review, test, operate, plan +- Software, repositories, infrastructure, or agent tooling +- Explicit invocation: `FP: fix the bug` or `$fp diagnose the failure` \ No newline at end of file diff --git a/fp/references/continuation.md b/fp/references/continuation.md new file mode 100644 index 0000000..8558ff2 --- /dev/null +++ b/fp/references/continuation.md @@ -0,0 +1,18 @@ +# Continuation Profile + +Load when resuming a previous session after compaction or session break. + +## Protocol + +1. **Revalidate context**: Task, repo, worktree, branch — confirm still matches +2. **Verify evidence**: Re-check previous acceptance criteria are still valid +3. **Never auto-replay writes**: All previous mutations must be verified, not assumed +4. **Re-establish state**: Re-read files that were being edited, re-run tests + +## Handoff Checklist + +- [ ] Task goal confirmed +- [ ] Repository state verified (branch, clean/dirty) +- [ ] Previous evidence re-checked +- [ ] No writes auto-replayed +- [ ] Current state matches session memory \ No newline at end of file diff --git a/fp/references/debug-incident.md b/fp/references/debug-incident.md new file mode 100644 index 0000000..00b8970 --- /dev/null +++ b/fp/references/debug-incident.md @@ -0,0 +1,20 @@ +# Debug Incident Profile + +Load when facing an unknown failure and the task is diagnosis-only (no fix yet). + +## Protocol + +1. **Pin the symptom**: Exact error message, timing, trigger conditions +2. **Read-only baseline**: Gather logs, metrics, state without mutation +3. **One falsifiable hypothesis**: Form a specific, testable theory +4. **One probe**: Run a single diagnostic test +5. **Narrow or pivot**: If probe narrows the cause, continue; if not, form new hypothesis +6. **Three non-narrowing probes → stop**: Switch to structural method (bisect, minimal reproduction, causal boundary trace) + +## Output + +- Location of failure +- Symptom observed +- Root cause (or `unknown` if not found) +- Evidence supporting conclusion +- Next step: fix proposal or further diagnosis needed \ No newline at end of file diff --git a/fp/references/delegated-execution.md b/fp/references/delegated-execution.md new file mode 100644 index 0000000..d02b5a9 --- /dev/null +++ b/fp/references/delegated-execution.md @@ -0,0 +1,22 @@ +# Delegated Execution Profile + +Load when delegating work to fresh agents or sub-processes. + +## Protocol + +1. **Bounded envelope**: Goal, scope, invariants, forbidden actions, output format +2. **Leaf constraints**: Cannot delegate further, deploy, use credentials, message externally, mutate live state +3. **Parent verification**: All subagent output is treated as claim, not evidence +4. **Idempotency key**: Each delegation has a unique key for deduplication +5. **Terminal cleanup**: Subagent resources are released on completion or timeout + +## Delegation Template + +``` +Goal: [one sentence outcome] +Scope: [exact files/dirs, read/write boundaries] +Invariants: [must not change or break] +Forbidden: [specific prohibited actions] +Output: [exact deliverable format] +Max: [iterations, time, depth limits] +``` \ No newline at end of file diff --git a/fp/references/live-system.md b/fp/references/live-system.md new file mode 100644 index 0000000..e0cdd69 --- /dev/null +++ b/fp/references/live-system.md @@ -0,0 +1,19 @@ +# Live System Profile + +Load when working with remote/stateful targets (OpenWrt, embedded, routers, production servers). + +## Protocol + +1. **Preserve management path**: Never close the only SSH/access route +2. **Create rollback**: Before any mutation, ensure a revert path exists +3. **Verify with real client path**: Test through the actual user-facing interface +4. **Resource ownership**: Confirm no other process holds locks/mutexes +5. **Lifecycle awareness**: Understand start/stop/restart behavior before touching services + +## Verification Checklist + +- [ ] Management path preserved +- [ ] Rollback tested or trivially reversible +- [ ] Real client path verified +- [ ] No resource conflicts +- [ ] Lifecycle handled (restart/reload as needed) \ No newline at end of file diff --git a/fp/references/multi-agent-review-protocol.md b/fp/references/multi-agent-review-protocol.md new file mode 100644 index 0000000..c834d21 --- /dev/null +++ b/fp/references/multi-agent-review-protocol.md @@ -0,0 +1,22 @@ +# Multi-Agent Review Protocol + +Load when multiple agents or sub-agents are writing in parallel. + +## Rules + +1. **Parent is integrator**: Default writer, final verifier +2. **Subagent envelope**: Goal, scope, invariants, forbidden actions, output format +3. **Leaf restrictions**: Cannot delegate, deploy, promote memory, message externally, use credentials, mutate live state +4. **One writer per shared file set**: Parallelize only independent investigation +5. **Parent reruns critical checks**: Subagent claims are not evidence + +## Handoff Format + +``` +Goal: [one sentence] +Scope: [files/dirs, read vs write] +Invariants: [must not change] +Forbidden: [actions not allowed] +Output: [expected deliverable] +Deadline: [max iterations/time] +``` \ No newline at end of file diff --git a/fp/references/provider-compatibility.md b/fp/references/provider-compatibility.md new file mode 100644 index 0000000..f87b331 --- /dev/null +++ b/fp/references/provider-compatibility.md @@ -0,0 +1,24 @@ +# Provider Compatibility Profile + +Load when encountering third-party proxy, gateway, retry loops, or encoding issues. + +## Detection + +- Repeated tool failures with the same error +- Encoding/garbled characters in API responses +- Connection resets or timeout loops +- Proxy/gateway between agent and model + +## Protocol + +1. **Isolate the layer**: Is the issue at the model, proxy, or tool level? +2. **Check encoding**: Verify request/response encoding matches provider spec +3. **Retry strategy**: Exponential backoff, max 3 retries, different transport if available +4. **Fallback**: If proxy is the issue, try direct connection or alternate route +5. **Report**: Document the failure pattern for future detection + +## Provider-Specific Notes + +- DeepSeek: v-final scores 3.14 vs 2.97 baseline in blind eval; benefits from structured routing +- OpenAI/Anthropic: Standard API behavior expected +- Custom providers: Validate against OpenAI-compatible API spec \ No newline at end of file diff --git a/fp/references/question-requirements.md b/fp/references/question-requirements.md new file mode 100644 index 0000000..16cd066 --- /dev/null +++ b/fp/references/question-requirements.md @@ -0,0 +1,22 @@ +# Question Requirements Profile + +Load when requirements are vague, risky, or underspecified. Challenge before building. + +## Protocol + +1. **Identify the gap**: What decision is missing? Who owns it? +2. **Generate 3 Idea Cards**, each with: + - **Title**: One-line summary + - **Assumption**: What we assume to be true + - **MVP scope**: Minimum viable delivery + - **Risk**: What could go wrong +3. **Present ranked**: Best option first with one-line rationale +4. **Wait for user choice**: Do not proceed until user picks a card +5. **Proceed as Medium**: After choice, execute with Execution Brief + evidence + +## When to Use + +- User request is "make it better" or "improve performance" +- Acceptance criteria are missing or fuzzy +- Multiple valid approaches with different tradeoffs +- High-risk change with unclear scope \ No newline at end of file