pi-anchorloop 0.0.0-stage → 2.0.0

package/skills/inspecting/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: inspecting
+description: Use when auditing or reviewing a specific target, diff, commit, or spec, or running final QA or a release-readiness check.
+---
+
+# Inspecting
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md). The anchor is that every scoped item has a verdict and its evidence.
+
+When a reviewer role contract is present, it governs scope, evidence, and report format; add only the Standards and Spec axes.
+
+## Playbooks
+
+- [diff-review](playbooks/diff-review.md): a branch, pull request, worktree, or change set.
+- [qa-release](playbooks/qa-release.md): final exploratory QA or release readiness.
+
+Any other target runs the flow below directly.
+
+## Inspection Flow
+
+### Phase 1: Scale the Inspection
+
+Choose the lightest mode that can support a trustworthy conclusion:
+
+- **Focused:** one narrow target or claim. Inspect it directly.
+- **Standard:** several clear items. State a concise checklist, then proceed.
+- **High-risk or ambiguous:** security, production, destructive effects, or unclear boundaries. Present the plan; wait for confirmation only in a review the user started directly.
+
+Include only dimensions relevant to the request: correctness, edge cases, architecture, security, performance, conventions, dependencies, and side effects. Take the blocking severity and the use to judge against from the assignment; without them, judge realistic use and count a rare edge case as blocking only when it loses, silently overwrites, or corrupts data.
+
+### Phase 2: Verify
+
+For each scoped item:
+
+1. Identify the evidence that would prove or disprove it.
+2. Gather that evidence directly. Invoke `investigating` only when the item requires substantial research or cross-source verification.
+3. Record a verdict: pass, fail, needs attention, or insufficient evidence.
+4. Grade the evidence as `investigating` defines. For a change judged safe, name the one fact its safety rests on and take it to `executed`.
+
+### Phase 3: Report
+
+```
+| Check Item | Verdict | Evidence / Notes |
+|------------|---------|------------------|
+| [item] | [verdict] | [evidence] |
+```
+
+Lead with the conclusion. Prioritize failures and recommended actions by impact. Name any unverified boundary instead of implying full coverage.
+

package/skills/inspecting/playbooks/diff-review.md

@@ -0,0 +1,57 @@
+# Diff review
+
+**You own a separate verdict on each axis, measured from a fixed point.**
+
+## Establish the evidence boundary
+
+1. Resolve the fixed point supplied by the user. When none is supplied, use the
+   clearly configured upstream or merge target; ask only when competing bases
+   would materially change the diff.
+2. Resolve its merge-base with `HEAD`. Capture the committed range, commit list,
+   `git diff HEAD` for staged and unstaged work, and `git status --short` for
+   untracked files. Inspect relevant untracked files directly. Stop with
+   insufficient evidence when the ref is invalid or the whole change set is
+   empty.
+3. Identify the governing spec in this order: user-supplied artifact, issue or
+   change reference in commits, branch-matching `docs/specs/` material, then the
+   confirmed conversation. Report “no spec available” when none can be proven.
+4. Identify repository standards, project instructions, ADRs, and relevant
+   architectural precedent.
+
+## Review independently
+
+Keep the axes separate even when evaluated in one session.
+
+### Standards
+
+Find each documented-standard violation and cite its source. Tool-enforced style
+is left to the tool. Use these smell heuristics only as judgment calls, with
+project precedent taking priority:
+
+- mysterious names and primitive domain concepts
+- duplicated logic or recurring conditionals
+- data clumps and feature envy
+- shotgun surgery or divergent responsibilities
+- speculative abstractions, pass-through middle layers, and message chains
+
+### Spec
+
+Map each requirement to the diff and report:
+
+- missing or partial behavior
+- behavior outside the approved scope
+- behavior that is present but implemented incorrectly
+- missing evidence for a claimed result
+
+Quote or point to the governing requirement for each finding. When no spec is
+available, mark this axis insufficient evidence instead of reconstructing intent
+from the implementation.
+
+**Reply:** separate `Standards` and `Spec` verdicts with file/hunk evidence, and
+a finding count and worst issue within each axis, never one combined score,
+because success on one axis cannot mask failure on the other.
+
+---
+
+Adapted from [mattpocock/skills](https://github.com/mattpocock/skills)
+`code-review` (MIT License, Copyright (c) 2026 Matt Pocock).

package/skills/inspecting/playbooks/qa-release.md

@@ -0,0 +1,9 @@
+# QA and release readiness
+
+**You own the findings ledger.** Use an active Mini SDD `verification.md` as the ledger; otherwise the project's QA convention, or `docs/qa/discover-qa-YYYY-MM-DD.md` when findings must persist.
+
+1. Discover: record the scope, version or branch, environment, and primary flows, then every unexpected behavior with reproduction steps. Cover only the edges that matter here: errors, boundaries, concurrency, permissions, data consistency. Discovery ends when every declared flow was exercised and every observation is in the ledger.
+2. Resolve each finding: trace it to a falsifiable root-cause hypothesis, hand a source fix to `coding` with the finding and repro as decision input, and take the anchor evidence it returns as the re-check. Record the evidence or the unresolved gap before the next finding.
+3. Commits and pushes belong to the workflow that authorized them.
+
+**Reply:** discovered, resolved, and deferred findings with evidence and owner. QA passes only when no unresolved finding contradicts the release criteria.

package/skills/investigating/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: investigating
+description: Use when researching questions, diagnosing root causes without fixing them, or gathering evidence.
+---
+
+# Investigating
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md). The anchor is the exact question and its completion boundary: answered, or the missing evidence named precisely.
+
+1. Gather evidence through the playbook below that fits the question.
+2. Cross-check material claims and resolve source conflicts.
+3. Grade each material claim by its strongest evidence: asserted, cited
+   (`file:line` or primary source), reasoned (the failure path walked and shown
+   not to reach), executed (a script or test against the real code), or
+   reproduced (observed in the running system). A claim with no evidence is
+   `unknown`.
+4. Report the reasoning chain with each material claim's source and grade beside it.
+
+## Playbooks
+
+- [research](playbooks/research.md): how something works, what is true, or why it was built this way.
+- [diagnose](playbooks/diagnose.md): why a running system misbehaves, when the deliverable is a diagnosis rather than a fix.

package/skills/investigating/playbooks/diagnose.md

@@ -0,0 +1,9 @@
+# Diagnose
+
+**You own the diagnosis.** The deliverable explains the symptom; a fix goes to the `coding` bug-fix playbook.
+
+1. Observe the symptom first through logs, metrics, traces, a profile, or a reproduction, before forming a theory from code.
+2. Write the candidate causes with the observation each predicts, and rule them out one at a time against runtime evidence.
+3. Confirm the surviving mechanism by a prediction that would fail if it were wrong.
+
+**Reply:** the symptom as observed, the mechanism with its evidence grade, the causes ruled out and how, and what a fix must change.

package/skills/investigating/playbooks/research.md

@@ -0,0 +1,9 @@
+# Research
+
+**You own the answer.** Read-only: the deliverable is a cited answer or a recommendation, not a change.
+
+1. Code: LSP (`read_symbol`) for symbols and ast-grep for structure; text search for prose, configuration, and literals; history (`git log -S`, blame) when the question is why or since when.
+2. External facts: current primary sources (official documentation, source code, specifications, first-party APIs) over summaries of them.
+3. **Observe, don't ask.**
+
+**Reply:** the answer first, then the chain with each claim's source and grade; for a choice, a trade-off table and a recommendation, pushing back when the premise is wrong.

package/skills/solid-loop/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: solid-loop
+description: Use when creating, editing, or auditing agent skills and instructions, applying friction notes, or bootstrapping or overhauling a project's agent system.
+---
+
+# Solid Loop
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md). The anchor is `uv run python hooks/validate_all.py .` or the project's own validator, clean, and every edited section passing the no-op test.
+
+The root virtue is **predictability**: each instruction sends the next run straight to the work, with no detour and no unneeded read.
+
+## Placement
+
+Put each fact where it stays true. One that holds for every task type goes to the `anchorloop` core; one that holds for one task type goes to its entry skill or playbook; one that holds for one project goes to that project's `AGENTS.md` or `CLAUDE.md`. A multi-step procedure no skill owns becomes a playbook, or a skill when no entry fits.
+
+## Mechanism
+
+Enforce at the highest level that works, because nothing fails when an agent skips prose: architecture that removes the wrong path; a script for repeated deterministic work; a type, lint, or test; a tool-loop lever (pi extension hook, stream rule, validator) for a check the model demonstrably skips, with a message that names the fix. Prove the check fails on the recorded mistake. Prose is for judgment calls. A `Found` fact the agent system already states in prose is a repeat: escalate it in the same change. List each enforced rule beside its enforcer in the owning instruction file's rule table, and drop the row once the mistake can no longer happen.
+
+## Hold the Size
+
+Pair each added sentence with a merge or deletion in the same file, so the file ends no longer than it began. When a fix exposes one fact stated in several places, keep one authoritative statement and replace the rest with a pointer or delete them. Run the no-op test on every section you edited and delete each sentence that fails. Keep each `SKILL.md` under 300 lines by moving reference into `references/` or a playbook.
+
+## Craft Levers
+
+- **Information hierarchy**: Ordered actions are steps, co-located rules are reference, and templates or deep catalogs live behind explicit context pointers.
+- **Leading words**: Anchor behavior with compact pretrained concepts (*tight*, *red*, *tracer*, *reality anchor*) instead of spelled-out explanations.
+- **Description as hook**: Write the situation in the user's own words that should send them here, assertively, because models under-trigger.
+- **Completion criteria**: Make each criterion checkable, and demanding enough to drive thorough legwork.
+- **Explain why**: Put the consequence beside the rule, and reserve capitals and absolutes for the one rule that causes real damage, stated once.
+- **Name the shortcut**: List the excuses the model will reach for as excuse → reality pairs, and turn adjectives into self-test questions.
+- **No-op test**: Evaluate each sentence in isolation and delete the ones that do not change behavior relative to the model's default.
+- **Single source of truth**: Give each operational contract one canonical home.
+- **Positive steering**: State the target behavior, because a prohibition names the unwanted pattern and makes it more likely; a prohibition or discipline skill keeps a negation only as an earned red line.
+- **Pin derived copies**: Record the upstream path and revision beside the credit of a skill, rule, or role derived from another source, and keep a check that fails when that upstream changes, so the derivation is redone instead of drifting.
+- **Earn the red line**: Admit a red line only when an observed failure backs it (a friction note's `Found` or a bare-run failure) and its reason or excuse → reality pair rides with it; delete the rest. The validator flags red-line inflation as an advisory.
+
+## Playbooks
+
+- [apply-friction](playbooks/apply-friction.md): classified friction notes from a Reflexive pass.
+- [author-skill](playbooks/author-skill.md): creating or editing a skill, playbook, or instruction file directly.
+- [bootstrap](playbooks/bootstrap.md): building or overhauling a project's agent system from investigation runs.
+
+## References
+
+- [Skill Template](references/template-skill.md)
+
+---
+
+Placement and mechanism adapted from [google-research/harness2](https://github.com/google-research/harness2) (Apache-2.0), revision `1cfe254`, `harness2/core/prompts.py`.

package/skills/solid-loop/playbooks/apply-friction.md

@@ -0,0 +1,15 @@
+# Apply friction notes
+
+**You own one action per note.** Notes arrive classified as `misdirection` or `gap` by the Reflexive pass.
+
+1. A note with no before/after contrast (the failed attempt and what revealed the cause) gets no placement; record it as unsupported.
+2. Correct each misdirection: open the line named in `Led by` and rewrite it to state what `Found` established, or delete it when it has no correct form.
+3. Place each gap: search the agent system for a statement of the `Found` fact. When one exists, the run could not reach it: sharpen the pointer or description that should have led there. When none exists, write it as one direct sentence where **Placement** puts it. A fact the change itself resolved, or a tool slip no project or skill owns, needs no placement.
+4. Choose the **Mechanism** before writing prose, then **Hold the Size**.
+
+**Reply:** one pair per note:
+
+```text
+Friction: <Found> (misdirection | gap)
+Action: <corrected line | sharpened pointer | placed at <location> | enforced by <check> | resolved by the change | unsupported>
+```

package/skills/solid-loop/playbooks/author-skill.md

@@ -0,0 +1,11 @@
+# Author a skill
+
+**You own the skill's behavior change, and nothing beyond it.**
+
+1. Name the layer: knowledge (what the model lacks), prohibition (a habit to block), process (an order), taste (an aesthetic), or discipline (shortcuts and false claims). The layer sets the length, the tone, and how much the description must carry.
+2. For a new skill or playbook, have the model attempt the task without it and record where it fails; the first version covers those failures and nothing more.
+3. A new skill starts from [the template](../references/template-skill.md); a new playbook copies an existing one's shape (ownership line, steps, `Reply:`).
+4. Apply the **Craft Levers**, then **Hold the Size**.
+5. Fix a broken skill met mid-task in its own change, not tangled into the task's diff.
+
+**Reply:** the files changed with the net line count of each, the layer, and the bare-run failures the change covers.

package/skills/solid-loop/playbooks/bootstrap.md

@@ -0,0 +1,10 @@
+# Bootstrap
+
+**You own an agent system built from evidence, not guesses.**
+
+1. Pick two to four investigation targets with falsifiable objectives: build and test reality (run the suites, typecheckers, linters), an architectural seam (trace one core flow end to end), and conventions (module structure, configuration, dependencies).
+2. Dispatch one isolated worker per target through `investigating`. Each records and classifies its friction notes and returns them instead of invoking `solid-loop`.
+3. Merge notes whose `Found` lines state the same fact.
+4. Apply the merged notes in one [apply-friction](apply-friction.md) pass.
+
+**Reply:** workers dispatched and their targets, each note with its action, and the components created or updated.

package/skills/solid-loop/references/template-skill.md

@@ -0,0 +1,26 @@
+# Streamlined Skill Template
+
+Use this template as a starting point when creating new skills.
+Keep the sections the skill's work needs and drop the rest.
+
+```markdown
+---
+name: <skill-name-gerund-or-action>
+description: Use when <one trigger per branch>.
+---
+
+# <Skill Name>
+
+<Single-paragraph overview stating the root virtue, objective, and operational context.>
+
+## Workflow
+
+1. **<Step 1 Name>**: <Direct statement of action and expected behavior.>
+   - **Completion Criterion**: <Observable, checkable condition confirming step is done.>
+2. **<Step 2 Name>**: <Direct statement of action and expected behavior.>
+   - **Completion Criterion**: <Observable, checkable condition confirming step is done.>
+
+## References
+
+- [Reference Name](references/<reference-file>.md)
+```

package/skills/writing/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: writing
+description: Use when writing or revising documentation, a README, an article, a PR description, or prose in general, tightening existing text, or cleaning up code comments.
+---
+
+# Writing
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md). The anchor is a reader without the conversation's context: hand the text to a fresh subagent and check it can say what the text asks of its reader. Comment-only work also keeps the project's tests green.
+
+Short declarative sentences; each claim carries its evidence or reads as an estimate. For Traditional Chinese articles, load `writing-in-weihung-voice` when it exists.
+
+## Playbooks
+
+- [draft](playbooks/draft.md): a new document.
+- [tighten](playbooks/tighten.md): revising or shortening existing text.
+- [comments](playbooks/comments.md): removing or rewriting code comments.

package/skills/writing/playbooks/comments.md

@@ -0,0 +1,10 @@
+# Comments
+
+**You own the comments, not the code.** No behavior changes.
+
+1. Keep a comment only for a non-obvious why the code cannot show: a constraint, a workaround with its cause, a surprising invariant.
+2. Delete comments that narrate what the code does, mark phases, or restate names; a test or script documents its step through its assertion text.
+3. When a comment claims a constraint the code could enforce (a type, an assertion, a check), report it as a follow-up.
+4. Verify that the diff touches only comments and that the project's tests still pass.
+
+**Reply:** comments removed and rewritten by count, the follow-ups, and the test result.

package/skills/writing/playbooks/draft.md

@@ -0,0 +1,10 @@
+# Draft
+
+**You own whether the reader can act on it.**
+
+1. Name the reader, what they already know, and the decision or action the text serves; open with that.
+2. Pick one mode (tutorial, how-to, reference, or explanation) and keep each section in it.
+3. Link to the source of a fact instead of copying it; a copied fact drifts.
+4. Open terms or decisions go to `grilling`, or to `domain-modeling` when they are domain terms.
+
+**Reply:** the document path, its reader and purpose, and the reader check's result.

package/skills/writing/playbooks/tighten.md

@@ -0,0 +1,9 @@
+# Tighten
+
+**You own the shorter text that says the same thing.**
+
+1. Delete before rewording: sentences that do not change what the reader does, restatements, hedges, and justification that manages a problem instead of fixing it.
+2. Merge what is stated twice into one place.
+3. Reword only what is left, keeping the author's voice and every fact.
+
+**Reply:** what was cut and why, the length before and after, and any fact you were unsure was safe to remove.