fp-finder-skill
Fixed-point convergence engine for skill files — SKILL.md and their references/*.md. Every accepted revision must be strictly shorter (per-file) AND still APPROVING per critical-review, with a factoring escape valve (new sibling whose baseline is bounded by chars moved from a parent that must itself strictly shrink) and a mutual-approval termination capped at N_max iterations. Designed to be dispatched from coordinate-review when the artifact is a SKILL.md, after generic FP loops on SKILL.md files grew unboundedly without converging. Use when you have one or more skill files and want to iterate them to a converged, brief, approved fixed point.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- fp-finder-skill
- description
- Fixed-point convergence engine for skill files — SKILL.md and their references/*.md. Every accepted revision must be strictly shorter (per-file) AND still APPROVING per critical-review, with a factoring escape valve (new sibling whose baseline is bounded by chars moved from a parent that must itself strictly shrink) and a mutual-approval termination capped at N_max iterations. Designed to be dispatched from coordinate-review when the artifact is a SKILL.md, after generic FP loops on SKILL.md files grew unboundedly without converging. Use when you have one or more skill files and want to iterate them to a converged, brief, approved fixed point.
03 SKILL.md 正文
fp-finder-skill
A skill-file-specialized fixed-point engine (SKILL.md files and the
references/*.md beside them). Every accepted revision must be strictly shorter per-file AND still APPROVING per critical-review. Termination is forced by per-file char-count decrease (Rule a), a parent-shrink + sibling-bound rule on factoring (Rule b), mutual approval, or an N_max = 8 cap. N_max = 8 is a guard against runaway iteration; longer-than-8 runs indicate a structural problem the loop alone won't fix and should escalate.
Char-count is a complexity proxy; APPROVING is the quality floor. A revision that is shorter but loses APPROVING does not count, so rm-style gaming fails: strip the body, the critic rejects, the loop returns the previous best. Per-file (not total-tuple) is the rule everywhere; factoring may grow the tuple, but each file individually still shrinks.
You are the driver
You — the agent invoked as fp-finder-skill — execute Steps 1–4 below, spawn the critic and revisor subagents, compute char-counts yourself, and decide the verdict on every gate.
Inputs
- artifact (required): a JSON array of one or more skill-file paths — SKILL.md files and/or
references/*.mdfiles under a skill directory — or a single path string. A file with no YAML frontmatter counts its whole content as body (for Rule (b) budgets and critic input alike). - reviewer_persona (optional): critic lens. Default: "Skeptical first-time reader of skill files."
State
current[path] = (text, wc_c)— latest accepted state per path. Initialize from inputs withwc_c = wc -c <path>.best[path]— shortest version ofpaththat has ever achieved APPROVING as part of a tuple-level APPROVING round (Loop Step 3 is the only promotion point; a per-path APPROVING inside a round whose tuple verdict failed never promotes — this keepsbesttuple-coherent); absent if none.iteration N, starts at 1.
All char-counts are computed by you via wc -c <path>. The revisor's self-report is reference only.
normalize(text) strips trailing whitespace per line and collapses runs of blank lines to one. Used in the "delta is not whitespace-only" check.
Subagent dispatch
Spawn subagents via the Task tool (general-purpose on Claude Code; equivalent dispatch primitive elsewhere). If the host environment lacks a dispatcher, run critic and revisor inline as separate prompts in the same session, one after the other. For each subagent skill (critical-review, revise-artifact), locate the file once via ls <repos-root>/agent-skills/skills/<name>/SKILL.md || ls ~/.claude/skills/<name>/SKILL.md, read it, strip the YAML frontmatter, and inline the body in the subagent prompt with the artifact text and any iteration context.
Tuple aggregation. For tuples of length > 1, spawn one critic per path. The tuple verdict is APPROVING iff every per-path verdict is APPROVING; otherwise the union of action items (tagged by path) is forwarded to the revisor.
Loop
Step 1 — Critic. Spawn critical-review per path; aggregate.
- APPROVING and
N == 1(initial input never been promoted): for each path, setbest[path] := current[path], then go to Step 4 withinitial_input_approved = true. - APPROVING and
N > 1: go to Step 4. - NEEDS-REVISION: collect action items; go to Step 2.
Step 2 — Revisor with monotone gate. Spawn revise-artifact with the action items AND this gate instruction verbatim:
Your revision must satisfy one branch per modified or new file:
(a) Shrink-in-place. For each pre-existing file you modify, strictly fewer chars than that file's input version, and the delta must not be whitespace-only.
(b) Factor. Move a self-contained chunk out of one pre-existing parent file into a NEW sibling file. The parent MUST end up strictly shorter than its input version (no "factoring" without parent-shrink). Per parent in this iteration, the sum of sibling sizes must not exceed the chars removed from that parent (so multiple siblings from one parent share a single budget). Per individual sibling: count only the body (everything after the YAML frontmatter) against the budget; the frontmatter is unavoidable overhead and is free.
You may combine (a) and (b) across files. Never pad, never copy-shift, never rename to inflate baselines. Report
chars_removed_from_parentandsibling_body_wc_cfor every Rule-(b) sibling so the driver can verify.
Step 3 — Validate then re-critique. You re-count every modified or new file with wc -c. Reject the revision and terminate (return best) if any check fails:
| Check | Applies to | Rule |
|---|---|---|
| Strict decrease | every modified pre-existing path | wc_c(new) < current[path].wc_c |
| Delta-not-whitespace | every modified file where wc_c(new) < wc_c(old) |
normalize(new) != normalize(old) |
| Sibling-budget | every parent that produced sibling(s) this iteration | sum(wc_c(sibling_body)) <= chars_removed_from_parent |
| Parent-shrunk on factor | every iteration with one or more new siblings | every named parent satisfies the Strict-decrease check above |
If all pass, spawn critical-review on the new tuple. If APPROVING: promote each changed/new path into current; update best[path] whenever shorter or absent; clear initial_input_approved (the input is no longer the fixed point). Increment N. If N > N_max, go to Wrap-up. Otherwise return to Step 1. If NEEDS-REVISION: revision fails the floor — discard and terminate (return best).
Step 4 — Mutual-approval termination. The critic has approved. Spawn the revisor exactly once with this prompt template (no variant phrasings):
The artifact tuple below has been approved by the critic. Either:
- Answer NO if you cannot identify a strict-shrink-or-factor change that would materially improve clarity, correctness, or completeness (your contract is to answer NO when no material improvement exists), OR
- Provide a concrete revised tuple as a Step-2 revisor would: state action items you want to address, then output the revised file content(s) and any factoring
chars_removed_from_parent/sibling_body_wc_cnumbers. Do not answer YES without a concrete revision payload.[current tuple]
NO → mutual approval; return best. Concrete revision → treat as Step 2 output (re-validate in Step 3) and continue.
Termination
Every accepted revision strictly decreases at least one file's char-count (Rule (a) decreases the modified file; Rule (b) decreases the parent via the Parent-shrunk-on-factor check). Char-counts are non-negative integers, so per-file budgets sum to finite. Factoring introduces new siblings, but the per-parent sibling-budget bounds the sum of sibling bodies by chars-removed from that parent — so the total system-wide body chars never grow more than they shrank on the same iteration. Frontmatter overhead per sibling is constant; total siblings created across all iterations is bounded by initial total parent body chars divided by the smallest meaningful factor, which is finite. N_max = 8 is the explicit backstop.
Returns
best[path]present: shortest APPROVING version of that path.best[path]absent (initial input never APPROVING, or a revision lost the floor before any APPROVING pass): return the path's initial text with note"no improvement confirmed."initial_input_approved = trueat termination: prefixbestwith note"converged at N=1; initial input was already a fixed point."- Factored-out parents: their
bestis the APPROVING version of the now-narrower parent. - Siblings created in an iteration whose re-critic then returned NEEDS-REVISION: omit from
best; return their text-on-disk with note"sibling created but iteration discarded; review manually." N_maxhit: prefix wrap-up with"stagnated at N_max iterations; returning best so far."
Pitfalls
- Padding gaming. Step 3's delta-not-whitespace + the critic's bloat detection together defend against whitespace and meaningless-token padding.
- Spurious factoring. A sibling with no consumer is dispatch overhead. The factored chunk must be self-contained, the parent's narrowed
descriptionmust still cover it, and the parent should reference the new sibling. - Revisor lying about chars. You always re-count via
wc -c. The revisor cannot evade. - Char-count rewards terseness over examples. Concrete examples may lose to abstract prose. The APPROVING floor protects against this: load-bearing examples removed → critic blocks → revision loses the floor.
- The proxy is not the goal. Minimize char-count subject to APPROVING; never for its own sake.
04 同仓库更多 Skills
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code