Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Change the shipped instructions to fix an observed defect, protect a high-risk b

Evaluate additions, removals, and retained complexity against the same outcome contract and total cost. For a material removal, identify the useful behavior, its surviving execution path, and the acceptance check. Missing behavioral evidence is uncertainty, not evidence that a required responsibility is unnecessary. Remove duplicates and contradictions without a paid experiment when inspection settles the result. Outside an explicitly requested optional workflow contract, add a mandatory step, role, gate, dependency, or persistent state only when evidence shows that capable agents cannot reliably infer the needed behavior and the benefit justifies its ongoing cost. Review each change for lost responsibility, autonomy, extra turns, maintenance cost, and provider assumptions.

Every runtime Markdown file fits one numbered tool view, which `scripts/check.py` enforces, because a failing shell read still loses the middle of a larger file. The kernel sits at that limit by design: an addition to it displaces text of equal size, and method belongs in the playbook that opens at the act. When the check's headroom lint names a playbook, tighten it in the change that brought it there, keeping its headings and responsibilities, rather than leaving the next addition to cut unrelated guidance.
Every runtime Markdown file stays short enough for a failing shell read with a short error line to show it whole, which `scripts/check.py` enforces in raw characters, because Claude Code still cuts a failing command's output to about 10,000 characters and agents read skill files with plain chained shell commands. The kernel sits at that limit by design: an addition to it displaces text of equal size, and method belongs in the playbook that opens at the act. When the check's headroom lint names a playbook, tighten it in the change that brought it there, keeping its headings and responsibilities, rather than leaving the next addition to cut unrelated guidance.

## Reviewing a change to the instructions

Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,21 @@

All notable changes to SkipHow 2.x and later appear in this file. Earlier release notes remain available on [GitHub Releases](https://github.com/mzored/SkipHow/releases).

## 6.3.5 (2026-10-16)

### Ownership at the change

- The kernel now asks every change to extend the code that owns a behavior instead of copying it. A replacement migrates in-repository callers and removes the old path and shims no outside consumer needs, and the guidance it makes stale.
- Technical design limits compatibility to consumers a change cannot update, such as published interfaces, deployed clients, and stored data. A compatible form kept for a staged migration goes when its callers finish. Where one implementation must keep owning a behavior and a new copy or use of a retired path would pass unnoticed, the playbook prefers a failing check to a comment or instruction.
- Operations keeps repository instructions and documentation to what code and tooling cannot show, and changes them with what they describe. The kernel opens it before writing repository guidance.
- The change follows a trace of two governed projects whose simplification audits returned 29 and 43 findings. Most consequential findings came from replacements that kept in-repository shims, new copies of rules an existing module owned, and guidance left stale. The method had lived only in a playbook that rarely loaded at those edits.

### Checks and evidence

- The runtime size gate counts raw characters against 9,900 instead of adding seven per line for a numbered view. Read showed a 36.7 KB file whole, and agents' shell reads of the kernel were almost all unnumbered. A failing shell command's output is still cut near 10,000 characters, so the gate keeps that bound with room for a short error line. Longer failure output still cuts, with a visible marker.
- Two unrun corpus scenarios use a new `owned-behavior` fixture whose grader-only oracles separate reuse from a copy of the rule and a retired path from a re-export shim. Deterministic tests show each oracle accepts a complete change and rejects the incomplete shapes.
- No paid model sessions or clean-install runs are required. The new behavior and comparative benefit remain `UNVERIFIED`.

## 6.3.4 (2026-10-11)

### Repository organization
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
6.3.4
6.3.5
4 changes: 2 additions & 2 deletions docs/decisions.md

Large diffs are not rendered by default.

22 changes: 19 additions & 3 deletions docs/evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,25 @@ Current package behavior remains `UNVERIFIED` unless a qualifying receipt names

## Current package

The 6.3.4 cleanup changes repository organization and documentation, with only version
metadata changed in the installable package. It adds no model-behavior claim. Retained
current-package CTO scenarios with Observed receipts remain 0 of 12. The corpus and
6.3.5 adds one kernel obligation at the act of changing code: extend the code that owns a
behavior instead of copying it, and let a replacement migrate in-repository callers and
remove the old path and shims no outside consumer needs, and the guidance it makes stale. Technical design and
operations carry the method. A maintainer trace of two owner projects run under 6.3.4
motivated it. Their broad simplification audits returned 29 and 43 findings, and most
consequential findings traced to three mechanisms: a replacement that kept in-repository
shims or re-exports, a new copy of a rule an existing module owned, and guidance not
updated with the code it described. Both audits stopped recurrence with failing checks
rather than instructions. Over the same weeks the kernel reached nearly every
source-editing Claude session, while the technical-design playbook loaded in 17 of 88
root sessions and 3 of 156 delegates. The trace is field evidence about where the debt
came from, not a receipt. The new behavior is `UNVERIFIED`, and its two corpus scenarios
are unrun.

The runtime size gate counts raw characters against 9,900 since 6.3.5. Measured on
2026-10-16, the Read tool showed a 36.7 KB file whole, 545 of 569 recorded shell reads
of the kernel were unnumbered, and a failing shell command's output was still cut near
10,000 characters. The 6.3.4 cleanup changed repository organization and documentation
only. Retained current-package CTO scenarios with Observed receipts remain 0 of 12. The corpus and
host ledger identify their candidate explicitly; historical receipts keep their
original package identities, outcomes, and hashes.

Expand Down
16 changes: 16 additions & 0 deletions docs/prior-art.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,22 @@ An idea from another project becomes a focused method or a kernel invariant only

The reasoning behind each rule that survived is in [decision history](decisions.md), and what real runs have and have not shown is in [current evidence](evidence.md).

## Ownership at the change in 6.3.5

Read on 2026-10-16 at Ponytail revision `84740e3d344b69b4a133201fa519eb37a62a2b2a`. Its
[implementation skill](https://github.com/dietrichgebert/ponytail/blob/84740e3d344b69b4a133201fa519eb37a62a2b2a/skills/ponytail/SKILL.md)
asks a change to list every caller, test, fixture, config, and export it must reach and to finish the callers it breaks,
and it fixes a bug once in the shared code. SkipHow's new kernel obligation agrees: a replacement migrates in-repository
callers. It goes further by removing the old path and the guidance it makes stale, and it limits compatibility to
consumers the change cannot update. The
[debt skill](https://github.com/dietrichgebert/ponytail/blob/84740e3d344b69b4a133201fa519eb37a62a2b2a/skills/ponytail-debt/SKILL.md)
collects `shortcut:` comments into a ledger. It is not adopted. The field trace behind this release found comments and
instructions did not stop recurrence, while failing checks did, and a persistent debt registry was already rejected.

The [architecture-improvement skill at `49dd158`](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/improve-codebase-architecture/SKILL.md)
remains a user-invoked scan with an owner-chosen candidate report. It adds no rule for retiring an old path, and its
owner-operated menu stays rejected as in 6.2.1. No source text or code is copied or adapted. Ponytail is MIT licensed.

## Planning review continuation in 6.3.1

Read on 2026-10-07. Superpowers' [scoped re-review prompt](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/re-review-prompt.md)
Expand Down
9 changes: 9 additions & 0 deletions evals/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,15 @@ implementation rather than trusting an edited oracle. `tests/test_simplification
fixtures through the existing helper and proves that the oracle accepts two complete repair shapes and rejects both
the unfixed implementation and a plausible transfer-only repair. It creates no Git repositories and starts no models.

The 6.3.5 ownership probes remain `UNVERIFIED`. `owned-rule-reused-for-new-guard` and `replacement-retires-old-path`
use `owned-behavior`. The first asks for a comment guard where `accounts.is_terminated` already owns the rule. Its
grader extends that rule in a scratch copy and requires the guard to follow it. The second asks for a move to a clock
module. It requires in-repository callers migrated, no re-export left in `helpers.py`, the stale `AGENTS.md` pointer
gone, and the documented partner entry point kept. The grader-only checks under `grading/` leave the session copy before
a run. The same fixture tests show that each oracle rejects the plausible incomplete shapes, a complete copy of the rule
and a re-export shim among them, and accepts a complete one. No arm without the candidate package is required to
produce the reuse or retirement event.

`design-native-capability-sufficient` and `design-native-capability-insufficient` use separate settled requirement
sections of `planning-readiness` as read-only recommendation probes. They reward native range selection where sufficient
and the maintained availability calendar where disabled dates are required, while rejecting omitted behavior and needless
Expand Down
Loading
Loading