@hobin/developer 0.1.0

package/skills/abstraction-review/references/field-card.md

@@ -0,0 +1,209 @@
+# Abstraction Review Field Card
+
+Use this reference when a review should produce more than a paragraph of advice.
+The goal is to turn a wished abstraction into an artifact with a stop check.
+
+## Contents
+
+- Operating Loop
+- Field Card
+- Source Modes
+- Good Wish Test
+- Recipe-Grade Gate
+- Layer Router
+- Minimal Output
+- Self-Application Check
+
+## Operating Loop
+
+```text
+pressure
+  -> wish
+  -> layer
+  -> recipe card
+  -> output artifact
+  -> observable stop
+  -> repair decision
+```
+
+The wish opens freedom; the stop check brings the review back to evidence.
+Failure is not handled by a better name. Failure exposes a broken layer,
+contract, or missing artifact.
+
+## Field Card
+
+Fill this card for serious reviews.
+
+```text
+Candidate:
+  What wished interface, helper, boundary, condition model, or abstraction is
+  being judged?
+
+Source and confidence:
+  Where did the candidate come from, and how strong is the evidence?
+
+Pressure:
+  What complexity, repetition, variation, history, or representation detail is
+  this candidate supposed to remove?
+
+Wish:
+  In the better world, what would callers be able to say or do?
+
+Mismatch:
+  What currently breaks or might break that wish?
+
+Timing:
+  pre-implementation / post-implementation
+
+Layer:
+  Language / Unit / Law / Boundary / Engine / Time / Run
+
+Recipe:
+  Which narrow card is being executed?
+
+Input artifact:
+  What concrete input must be written before judgment?
+
+Derivation:
+  How does that input constrain the output?
+
+Contract:
+  What can callers or future users rely on?
+
+Hidden detail:
+  What representation, policy, timing, history, cost, or process detail should
+  callers not depend on?
+
+Output artifact:
+  What table, graph, contract, invariant, trace, or decision remains?
+
+Stop:
+  What observable check decides pass/fail?
+
+Evidence and gaps:
+  What evidence supports the decision, and what would change it?
+
+Decision:
+  keep / revise-surface / revise-model / split / reject / defer
+
+Open consequence:
+  What remains unresolved after this review?
+```
+
+## Source Modes
+
+Use the candidate source to choose evidence and timing.
+
+| Source | Review pressure | Evidence to require |
+| --- | --- | --- |
+| design draft wished interface | Is the wish implementable and bounded? | caller contract, representative cases, hidden detail, planned stop |
+| structural observation | Is the movement real abstraction or local churn? | before/after diff, repeated movement, condition relation |
+| user-proposed API/helper | Is it domain language or implementation-shaped naming? | wished use, caller obligations, failure modes |
+| existing implementation | Does code still match the abstraction promise? | tests, trace, cost, call sites, hidden coupling |
+| skill/workflow update | Will future agents behave differently? | trigger wording, reference routing, realistic invocation |
+
+## Good Wish Test
+
+A wish is strong enough to review when it exposes a small language, not merely a
+preferred name.
+
+```text
+primitive words:
+  What operations can be trusted without re-opening implementation detail?
+
+means of combination:
+  How do smaller units produce larger valid units?
+
+means of abstraction:
+  How is a repeated composition or method given a reusable handle?
+```
+
+Reject or revise a wish when:
+
+- it only renames current representation shape;
+- it has no caller contract or failure mode;
+- its result cannot be composed or intentionally finalized;
+- no preserved meaning, invariant, or policy owner is visible;
+- it hides cost, history, order, or mutation that callers must understand.
+
+## Recipe-Grade Gate
+
+A review is recipe-grade only when this sentence can be filled:
+
+```text
+Given <input artifact>,
+derive <output artifact>
+by <rule>,
+then check <observable stop>.
+If it fails, repair <layer, contract, or artifact>.
+```
+
+If the sentence cannot be filled:
+
+| What it is | Missing | Review consequence |
+| --- | --- | --- |
+| Advice | trigger, artifact, stop check | keep as explanation; do not promote |
+| Heuristic | derivation from input to output | read `repair-table.md` or expose the missing model |
+| Candidate recipe | derivation is still loose | run one worked case |
+| Recipe-grade | trigger, input, rule, output, stop, repair all exist | use in the review |
+
+## Layer Router
+
+| Symptom | Layer | First card |
+| --- | --- | --- |
+| The problem vocabulary is missing or misleading | Language | Notation As Data |
+| Similar functions, workflows, or tests move together | Language/Unit | Movement Pattern Extraction |
+| Operation results do not remain composable | Unit | Closure Composition Unit |
+| A loop, state transition, or contract has no preserved meaning | Law | Invariant Iteration |
+| Callers must know raw representation or hidden policy | Boundary | Data Abstraction Boundary |
+| New variants keep changing old conditionals | Engine | Dispatch Registration |
+| Conversion works but meaning loss is hidden | Engine/Law | Meaning-Preserving Path |
+| Same call depends on past interaction | Time | History Placement |
+| Event order changes correctness | Time/Run | Event Order Protection |
+| Result is right but process, cost, sharing, or stack shape is wrong | Run | Procedure -> Process Reality Check |
+
+When the symptom is clearer than the layer, open `repair-table.md`.
+
+## Minimal Output
+
+For a compact user-facing review, show:
+
+```text
+Candidate:
+Source and confidence:
+Layer:
+Recipe:
+Input artifact:
+Derivation rule:
+Contract:
+Hidden detail:
+Output artifact:
+Stop check:
+Evidence and gaps:
+Decision:
+Open consequence:
+```
+
+When this review is part of a larger task, return the decision and its open
+consequence. The caller or orchestrator decides what happens next. Otherwise,
+stop at the review result. The card must be complete enough that a later person
+or agent can use it without reconstructing the reasoning.
+
+## Self-Application Check
+
+When the candidate is a skill, workflow, recipe, or reference update, review the
+update with the same card.
+
+Map the layers this way:
+
+| Skill update surface | Review layer |
+| --- | --- |
+| trigger wording, user-facing command language | Language |
+| skill responsibility and core question | Boundary |
+| recipe-grade invariant or stop condition | Law |
+| progressive disclosure and reference routing | Engine |
+| whether future agents actually read enough context | Run |
+
+The stop check should be a realistic invocation, self-review card, or
+forward-test prompt. If the review cannot name what future behavior changes, the
+update is probably documentation, not a stable workflow abstraction.

package/skills/abstraction-review/references/recipe-cards.md

@@ -0,0 +1,255 @@
+# Abstraction Review Recipe Cards
+
+Use this deck when the review needs a construction rule, not only a layer name.
+Each card must produce an artifact and a stop check.
+
+## Contents
+
+- Pocket Deck
+- Procedure -> Process Reality Check
+- Movement Pattern Extraction
+- Invariant Iteration
+- Data Abstraction Boundary
+- Closure Composition Unit
+- Dispatch Registration
+- Meaning-Preserving Path
+- Notation As Data
+- History Placement
+- Event Order Protection
+
+## Pocket Deck
+
+| Card | Trigger | Fill first | Derive | Stop | Repair if fails |
+| --- | --- | --- | --- | --- | --- |
+| Procedure -> Process Reality Check | Result is plausible but process shape is unclear | procedure text, sample input, expected result | trace deferred work, state updates, duplicated work, cost | result, shape, and cost are all explainable | move to Law or Time |
+| Movement Pattern Extraction | Similar cases move together but differ in stable roles | concrete cases side by side, common movement, varying roles | keep common movement as body; lift stable variation roles to parameters, callbacks, or strategies | old cases become simple calls and new case is expressible | split, inline, or return to Language |
+| Invariant Iteration | Recursion or state should become a stable transition | original meaning, state variables, transition candidate | write `processed meaning + remaining meaning = original meaning` using the domain operation | initial, step, and final checks pass | return to Run trace or reduce state variables |
+| Data Abstraction Boundary | Caller knows raw representation | domain value, operations, representation candidates | create constructor, selector, predicate, and operation vocabulary | caller code stops touching raw representation | move to Unit or Engine |
+| Closure Composition Unit | Operation results cannot feed later operations | candidate unit, operation list, preserved meaning | mark closed operations vs observers/finalizers | closed operations build larger values of the same unit | move final effect outside the unit |
+| Dispatch Registration | New type/provider/case changes old branches | variant axis, operation axis, current branches | turn each branch into `(variant, operation) -> method` | fake variant is added by registration only | choose axes again or use Meaning-Preserving Path |
+| Meaning-Preserving Path | Mixed worlds need operation without hidden loss | source worlds, operation, candidate paths | draw direct/coerce/canonicalize/reject graph | legal path, loss, and unsupported cases are explicit | narrow preserved meaning or reject |
+| Notation As Data | String/index manipulation stands in for semantic rules | expression cases, parts, transformations | make predicate/selector/constructor vocabulary | rewrite rule ignores raw layout | move to Boundary or Engine |
+| History Placement | Same call depends on history | behavior, required history, interaction model | choose pure, local state, or stream/log placement | hidden summary or explicit history matches contract | move to Event Order or Boundary |
+| Event Order Protection | Interleaving changes correctness | events, shared meaning, possible interleavings | state order law and protected region or merge policy | forbidden interleaving is blocked for a stated reason | narrow order law or return to History |
+
+## Card Details
+
+### Procedure -> Process Reality Check
+
+Use when code is textually simple but execution may grow the wrong process.
+
+Output artifact:
+
+```text
+process trace:
+  input -> stage -> stage -> result
+shape:
+  recursive / iterative / tree / delayed / stateful
+cost note:
+  time, space, duplicated work, hidden order
+```
+
+Promote only if the abstraction promise includes the real process shape, not
+just the returned value.
+
+### Movement Pattern Extraction
+
+Use when abstraction pressure comes from repeated movement, not from a single
+interface wish.
+
+Input artifact:
+
+```text
+cases:
+  two or more concrete functions, workflows, tests, or traces
+common movement:
+  steps that move together across cases
+variation roles:
+  stable differences such as predicate, term, next, combine, strategy, policy
+```
+
+Derivation:
+
+```text
+body:
+  keep the common movement
+parameters:
+  lift stable variation roles
+name:
+  describe the concept, not the implementation trick
+```
+
+Output artifact:
+
+```text
+abstraction candidate:
+  name, signature, body skeleton
+role table:
+  case -> variation role values
+process note:
+  whether the generated process/cost changes
+```
+
+Stop check: each old case is a simple call, and at least one realistic new case
+can be expressed without adding a new option that exposes internals.
+
+Reject if the cases only look textually similar but carry different
+responsibilities. Split if variation roles are not stable.
+
+### Invariant Iteration
+
+Use when state variables or accumulators need meaning.
+
+Output artifact:
+
+```text
+invariant:
+  what state variables preserve
+initial:
+  why the invariant starts true
+transition:
+  why one step keeps it true
+final:
+  why termination exposes the answer
+```
+
+If the invariant is hard to state, decide `revise-model`. If it is true but
+expensive, review representation or operation placement.
+
+### Data Abstraction Boundary
+
+Use when callers know too much.
+
+Output artifact:
+
+```text
+public handles:
+  constructors / selectors / predicates / generic operations
+representation law:
+  what callers may trust
+hidden freedom:
+  internal details that may change
+creation policy:
+  validation / normalization / simplification location
+```
+
+If no detail is hidden, reject or inline. If policy is hidden in consumers,
+decide `revise-surface`.
+
+### Closure Composition Unit
+
+Use when the goal is an algebra of reusable pieces.
+
+Output artifact:
+
+```text
+unit predicate:
+  what belongs to the world
+closed operations:
+  unit -> unit, unit x unit -> unit
+observers/finalizers:
+  unit -> outside
+illegal move:
+  operation that leaks or breaks the unit
+```
+
+Do not make everything chainable. Preserve the central unit and move final
+effects to an explicit boundary.
+
+### Dispatch Registration
+
+Use when variation should be additive.
+
+Output artifact:
+
+```text
+table:
+  variants x operations
+registration:
+  register(variant, operation, method)
+lookup:
+  applyGeneric(operation, value...)
+unsupported:
+  explicit missing capability policy
+```
+
+Stop check: add a fake variant. Existing callers and existing variant packages
+should not know its representation.
+
+### Meaning-Preserving Path
+
+Use when values cross worlds.
+
+Output artifact:
+
+```text
+conversion graph:
+  source -> target paths
+preserved meaning:
+  what must survive conversion
+policy:
+  direct / raise / canonicalize / reject
+loss note:
+  precision, identity, ordering, capability
+```
+
+Unsupported is a legitimate boundary, not a failure, when meaning cannot be
+preserved.
+
+### Notation As Data
+
+Use when a language, expression, query, or formula must be inspected or
+rewritten.
+
+Output artifact:
+
+```text
+expression boundary:
+  predicates / selectors / constructors
+transform rules:
+  algorithms written against the boundary
+render/evaluate boundary:
+  where data becomes displayed or executable again
+```
+
+If transformation rules depend on indexes or string layout, the boundary is not
+real yet.
+
+### History Placement
+
+Use when current behavior cannot be understood from current input alone.
+
+Output artifact:
+
+```text
+placement:
+  pure / local state / stream-log
+state contract:
+  what hidden state summarizes
+stream contract:
+  what each time-indexed value means
+order risk:
+  where histories merge or conflict
+```
+
+Local state hides history for API simplicity. Stream/log exposes history for
+composition, replay, audit, and merge reasoning.
+
+### Event Order Protection
+
+Use when order is part of meaning.
+
+Output artifact:
+
+```text
+order law:
+  required happens-before relation
+protected region:
+  steps that must appear atomic
+mechanism:
+  lock / transaction / queue / serializer / merge policy
+cost:
+  waiting, reduced parallelism, fairness tradeoff
+```
+
+If everything must be serialized, the order law is probably too broad.

package/skills/abstraction-review/references/repair-table.md

@@ -0,0 +1,98 @@
+# Abstraction Review Repair Table
+
+Use this table when a wished abstraction failed, or when the observed symptom is
+clearer than the broken layer.
+
+## Diagnostic Loop
+
+```text
+observed mismatch
+  -> evidence
+  -> broken layer hypothesis
+  -> recipe card
+  -> repair output
+  -> re-run same symptom
+```
+
+Do not jump from mismatch to a better name. Names can be repair outputs, but the
+repair must change a layer, contract, or artifact.
+
+## Repair Log
+
+```text
+Observed symptom:
+Evidence:
+Broken layer hypothesis:
+Selected recipe:
+Repair output:
+Re-run result:
+Open consequence:
+```
+
+If the repair output is empty, the review only explained the problem.
+
+## Repair Matrix
+
+| Symptom | Suspect layer | First repair | Output to create | Stop check |
+| --- | --- | --- | --- | --- |
+| Helpers have nice names but the domain rule is invisible | Language | Restate desired vocabulary | primitive/combination/abstraction vocabulary | new case can be spoken without representation detail |
+| Similar functions differ only by predicate, term, next step, or strategy | Language/Unit | Movement Pattern Extraction | common movement plus variation role table | old cases become simple calls |
+| Similar-looking code has different responsibilities | Unit/Boundary | Reject or split the abstraction | responsibility split note | no shared unit is promoted |
+| Caller reads object fields, list indexes, tags, or provider-specific shape | Boundary | Data Abstraction Boundary | constructor/selector/predicate/operation list | caller no longer touches representation primitive |
+| Operation result cannot be fed into later operations | Unit | Closure Composition Unit | closed operation table | closed operations build larger units |
+| Chainable API forces final side effects into the chain | Unit/Boundary | Split closed operations from finalizers | observer/finalizer boundary | closed operations and boundary effects are distinct |
+| State variables have no meaning | Law | Invariant Iteration | invariant statement | initial/step/final checks pass |
+| Loop is fast but correctness cannot be explained | Law/Run | Invariant + process trace | invariant and process trace | correctness follows from preserved meaning |
+| Recursive version is clear but stack or deferred work grows | Run | Procedure -> Process, then Invariant | shape note and accumulator option | shape change is explicit |
+| Constructor, validator, and normalizer are scattered | Boundary/Engine | Creation policy boundary | creation policy note | value enters the world through one gate |
+| Constructor is too expensive | Engine/Run | Cost placement decision | create/read/update cost note | cost owner is explicit |
+| New representation changes old code | Engine | Dispatch Registration | variant x operation table | new row/package is enough |
+| New operation changes every variant | Engine | Re-evaluate row/column axis | axis decision | frequently growing axis is explicit |
+| Mixed types explode into direct cases | Engine/Law | Meaning-Preserving Path | conversion graph | legal, loss, and unsupported paths are visible |
+| Conversion loses precision, identity, order, or capability | Law | Narrow preserved meaning | loss note | loss appears in contract |
+| Expression rewrite uses strings or indexes | Language/Boundary | Notation As Data | expression selectors/constructors | rules ignore raw layout |
+| AST exists but transforms are representation-specific | Boundary | Data Abstraction Boundary | representation-independent rules | representation can change |
+| Same call returns different results after prior interactions | Time | History Placement | state/history contract | history location is explicit |
+| Caller keeps passing previous state everywhere | Time/Boundary | History Placement | local state decision | burden is intentionally hidden or kept explicit |
+| Local state makes testing/reasoning hard | Time/Run | History Placement + process trace | hidden history note | loss of referential transparency is accepted |
+| Undo, replay, audit, or collaboration needs past events | Time | History as stream/log | stream/log decision | history is manipulable data |
+| Stream merge changes meaning | Time/Run | Event Order Protection | merge/order policy | forbidden interleaving is explainable |
+| Concurrent read-compute-write breaks invariant | Time/Run | Event Order Protection | protected region | invariant-breaking interleaving is blocked |
+| Lock/serializer blocks too much | Time/Engine | Narrow the order law | smaller protected relation | only meaningful order is protected |
+| Generic abstraction is clean but slow | Run/Engine | Procedure -> Process | cost surface | dispatch/lookup/coercion cost is visible |
+| Everything feels abstract and nothing is actionable | Run | Field Card + Recipe Cards | selected recipe card | trigger/input/output/stop are filled |
+
+## Collision Rules
+
+| Collision | Prefer first when evidence says... | Then check... |
+| --- | --- | --- |
+| Language vs Boundary | caller has no useful words except representation details | whether a boundary is still needed after vocabulary exists |
+| Movement vs Duplication | cases share behavior roles, not just text | whether old cases become simpler and responsibility stays coherent |
+| Unit vs Boundary | results leave the composable world | observer/finalizer separation |
+| Law vs Run | result is right but why is unclear | invariant first, then process shape |
+| Boundary vs Engine | caller knows internal details | boundary first, then registry/table placement |
+| Engine vs Law | dispatch/conversion works but meaning loss hides | preserved meaning, then path graph |
+| Time vs Boundary | same call changes with history | whether history is public contract or hidden state |
+| Time vs Run | delayed execution or event order changes correctness | order law or process trace |
+| Run vs Engine | abstraction is semantically right but costs too much | cost trace, then dispatch/coercion placement |
+
+## Exit Checks
+
+Before leaving the table, check:
+
+```text
+Symptom:
+  Did the review name the actual mismatch?
+
+Evidence:
+  Was the mismatch observed in caller code, trace, test, cost, history, or order?
+
+Layer:
+  Is the layer a likely cause, not merely a consequence?
+
+Recipe:
+  Does the selected card require an output artifact?
+
+Re-run:
+  Did the same symptom disappear, remain, or become a new symptom?
+```