@hobin/developer 0.1.1 → 0.1.3

package/skills/naming-judgment/references/elements-of-clojure-naming.md

@@ -1,74 +0,0 @@
-# Elements Of Clojure Naming Notes
-
-These notes adapt naming ideas from Zachary Tellman's *Elements of Clojure*
-(2019), especially the `Names` chapter and the beginning of `Indirection`. Use
-them as judgment prompts, not hard rules.
-
-## Core Observations
-
-- Names are a common form of indirection. A name lets a reader stop at what the
-  code means without reading how it works.
-- A name has a textual sign, a current referent, and a sense. In software, the
-  sense matters most because the referent can change while callers keep relying
-  on the same idea.
-- Narrow does not mean maximally specific. A too-general name hides necessary
-  properties; a too-specific name exposes implementation details that should be
-  free to change.
-- Consistency is contextual. A name is understood through local code, domain
-  language, ecosystem conventions, documentation, and conversation.
-- Natural names help readers reason by analogy but carry multiple senses.
-  Synthetic names can be precise for experts but create a cliff for new readers.
-- A name can be valid in one audience or namespace and misleading in another.
-  Reusing a natural word across different product contexts requires active
-  boundary management.
-
-## Data Names
-
-- Data names should communicate the invariant or role readers can rely on, not
-  every structural detail.
-- A function parameter only controls the sign; the caller controls the value. If
-  the name assumes an invariant, enforce it at the boundary where outside data
-  enters.
-- A local binding name should let the reader skip the right-hand expression. If
-  the name does not improve skimming, prefer direct composition or keep the
-  expression inline.
-- Avoid naming every intermediate value. Introduce a name when it adds a stable
-  concept or removes real cognitive load.
-- Collection and map shape can help when it distinguishes real cases. Prefer
-  local project conventions over imported notation.
-
-## Function Names
-
-- Functions pull data into scope, transform data already in scope, push data into
-  another scope, or combine those actions.
-- A function that crosses a data-scope boundary should usually have a verb.
-- A pure transform can often be named by its result, property, or conversion
-  rather than a generic verb.
-- A function that both pushes and returns data should make the combined behavior
-  explicit or be split.
-- Namespace/module context can narrow function names. If every function operates
-  on the same domain object or data scope, the repeated noun can often move to
-  the module boundary.
-
-## Indirection And Modules
-
-- Indirection separates what from how and gives permission not to inspect deeper
-  layers.
-- A software module can be viewed as model, interface, and environment. Names
-  live on the interface side: they describe what the model is and what it is
-  expected to become.
-- An abstraction is useful only in an environment. A name that is internally tidy
-  but wrong for the product context is not a good name.
-- Every model omits facets of the environment; the omissions become assumptions.
-  Names should not quietly turn fragile assumptions into permanent facts.
-
-## Practical Review Prompts
-
-- What does this name let a reader safely ignore?
-- Which property must remain true if the implementation changes?
-- Is the name too close to the current implementation, storage, UI widget, or
-  library?
-- Is the name too broad to exclude invalid uses?
-- Is a natural word carrying different senses in different parts of the system?
-- Would a shorter name become clear if this code moved into a better module?
-- Is the name hiding a side effect, external boundary, or mutation?

package/skills/signal/references/flocking-and-structural-movement.md

@@ -1,157 +0,0 @@
-# Flocking And Structural Movement
-
-Use this reference when duplication, parallel branches, similar tests, repeated
-UI states, conditionals, or a recent refactor create pressure for structural
-movement and the safest next move is not obvious.
-
-## Contents
-
-- Change Pressure
-- The Flocking Cycle
-- Evidence That Keeps The Move Green
-- Horizontal And Vertical Movement
-- Model-Code Mismatch
-- Small-Step Discipline
-- Failure Checks
-- Reporting Shape
-- Conceptual Lineage
-
-## Change Pressure
-
-Start with the current requirement or invariant. Ask whether the existing code
-is already open to the change. If it is, similarity alone does not justify a
-refactor. If it is not, locate the smallest part of the code whose present shape
-blocks or obscures the change.
-
-Structural movement should answer an observed pressure:
-
-- two paths express the same responsibility differently;
-- a stable domain difference is hidden in incidental branching;
-- a default or absence policy is duplicated;
-- a modeled transition is represented as an unrelated current-state check;
-- callers repeat knowledge that should belong behind a boundary;
-- names describe mechanics while the model describes meaning.
-
-## The Flocking Cycle
-
-Work with one selected pair at a time:
-
-1. Select the two things most alike.
-2. State why they are alike: responsibility, vocabulary, transition, failure
-   mode, model element, or user-visible outcome.
-3. Find the smallest meaningful difference between only those two things.
-4. Choose the simplest behavior-preserving move that removes or exposes that
-   difference.
-5. Run the smallest relevant check.
-6. Observe the new shape before choosing another pair.
-7. Delete newly unused code only after the replacement is exercised.
-
-Possible small moves include matching an expression or name, aligning a branch,
-introducing a temporary parameter or adapter, moving one responsibility, or
-calling the new shape before deleting the old one.
-
-If the proposed move changes behavior, touches many unrelated sites, or creates
-a public concept, it is no longer a routine flocking step. Split it or return a
-vertical/ambiguous candidate for review.
-
-## Evidence That Keeps The Move Green
-
-"Behavior preserving" is a claim, not a visual impression. Name the evidence:
-
-- focused tests for the affected responsibility;
-- a characterization test for legacy behavior;
-- typecheck, build, or contract evidence for an interface movement;
-- a representative UI or integration check;
-- a diff inspection showing only structural change;
-- an explicit residual when no cheap verifier exists.
-
-Lower confidence when evidence cannot distinguish the original and moved
-behavior. Do not use a broad green suite as proof when it never exercises the
-selected difference.
-
-## Horizontal And Vertical Movement
-
-Keep movement horizontal when it aligns already-related code inside the current
-abstraction level and leaves no stable new concept behind.
-
-Treat movement as vertical only when, after the difference is understood, a
-nameable concept remains:
-
-- a policy with its own cases;
-- an invariant-bearing boundary;
-- a responsibility with distinct reasons to change;
-- a conversion or representation barrier;
-- state/history ownership;
-- a caller contract shared across uses.
-
-Similarity is not enough. Two pieces may look alike while changing for
-different reasons. Conversely, a vertical concept may first appear as a stable
-difference rather than as duplicated text.
-
-For a vertical or ambiguous candidate, state its pressure, contract-shaped
-meaning, hidden detail, invariant risk, concrete evidence, and evidence still
-needed. Do not promote or schedule it here.
-
-## Model-Code Mismatch
-
-When a problem model exists, check whether code and model disagree:
-
-- a forbidden case remains representable or reachable;
-- a decision space has a missing or conflicting branch;
-- a transition rule sees only the current state and loses history;
-- a caller does not establish a callee precondition;
-- a type admits invalid states without a boundary check;
-- progress or retry behavior is absent from a temporal requirement;
-- a ranking or objective is hidden in incidental ordering;
-- product vocabulary and code vocabulary point to different concepts.
-
-A mismatch may justify structural review even without textual duplication.
-
-## Small-Step Discipline
-
-Keep each move reversible and locally explainable. After every green move,
-reselect the comparison instead of executing a predetermined refactoring plan.
-The newly aligned code may reveal that the next difference is meaningful and
-should remain.
-
-When a move fails its check, revert or repair that move before continuing. Do
-not stack more structural guesses on top of ambiguous evidence.
-
-## Failure Checks
-
-The observation is not ready when:
-
-- no selected pair is named;
-- "duplicate" is the only similarity basis;
-- the smallest difference is actually several differences;
-- the move has no behavior-preserving evidence;
-- a helper is proposed before its stable concept can be stated;
-- line count or static complexity is treated as the only improvement measure;
-- product scope is expanded during structural observation;
-- timing is decided before a concrete candidate exists.
-
-## Reporting Shape
-
-Keep the result auditable:
-
-```text
-Pressure: the requirement, invariant, or mismatch driving observation
-Selected pair: the two most alike artifacts and why
-Smallest difference: one concrete distinction
-Smallest move: one behavior-preserving experiment
-Evidence: the check that keeps the move green
-Classification: no-signal | horizontal | vertical | ambiguous
-Candidate: only for vertical or ambiguous movement
-Missing evidence: what could change the classification
-```
-
-## Conceptual Lineage
-
-This reference adapts the flocking rules and small, behavior-preserving
-refactoring discipline presented by Sandi Metz, Katrina Owen, and TJ Stankus in
-*99 Bottles of OOP*. It extends the comparison with model-code mismatch and
-explicit evidence because the skill must judge real product changes, not only
-remove duplication.
-
-- 99 Bottles of OOP: https://sandimetz.com/99bottles
-- JavaScript sample: https://sandimetz.com/99bottles-sample-js

package/skills/sketch/references/design-recipe-and-abstraction-barriers.md

@@ -1,169 +0,0 @@
-# Design Recipe And Abstraction Barriers
-
-Use this reference when a sketch must do more than name files or helpers: the
-data shape, ownership, traversal, representation boundary, or wished interfaces
-must carry part of the design judgment.
-
-## Contents
-
-- Design Pressure
-- Data Definitions And Templates
-- Wishful Top-Level Design
-- Wished Interfaces As Barriers
-- Representative Cases And Checks
-- Deferred Abstractions
-- Failure Checks
-- Compact Example
-- Conceptual Lineage
-
-## Design Pressure
-
-A useful sketch preserves a chain of reasoning:
-
-```text
-accepted intent
--> purpose
--> data or state definitions
--> representative cases
--> data-shaped template
--> wishful top level
--> wished interfaces and checks
--> smallest implementation item
-```
-
-Do not start with a file list. A file list records placement after the design is
-known; it does not explain why the design has that shape.
-
-## Data Definitions And Templates
-
-A data definition does more than repeat a type name. State:
-
-- what domain information the data represents;
-- which values are valid members;
-- which values are excluded or impossible;
-- which variants, lifecycle states, or ownership boundaries matter;
-- which fields are available at each branch or traversal point.
-
-Derive the template from that definition. The template should expose the
-structural inventory an implementation must handle:
-
-- one branch for each meaningfully different variant;
-- selectors or fields available in each branch;
-- recursive or collection traversal positions;
-- state transitions and the old/new values they require;
-- ownership handoffs and conversion boundaries.
-
-Merging two branches is allowed only when the accepted intent treats them the
-same. Omitting a branch requires an explicit reason, such as an upstream
-guarantee that makes the state unreachable.
-
-The template is not final code. It is the smallest skeleton that makes missing
-cases, hidden state, and accidental representation choices visible.
-
-## Wishful Top-Level Design
-
-Write the top-level operation as if the right lower-level operations already
-existed. Use the vocabulary of the product contract and problem model rather
-than storage, framework, DOM, transport, or mutation mechanics.
-
-Wishful top-level design should reveal:
-
-- the order of domain operations;
-- which decisions belong at the top level;
-- which details callers should not need to know;
-- which missing concepts need names and contracts;
-- where evidence can check the result.
-
-Do not invent a helper only to shorten code. A wished operation earns a name
-when its purpose and caller-facing assumption can be stated without describing
-its body.
-
-## Wished Interfaces As Barriers
-
-Treat each wished interface as a proposed abstraction barrier. Record:
-
-- purpose: what callers obtain or may assume;
-- input and output shape;
-- contract: preconditions, postconditions, and meaningful failure;
-- owner: the component or layer responsible for the guarantee;
-- hidden detail: representation or mechanism callers must not depend on;
-- stop check: the smallest evidence that would falsify the contract.
-
-An interface is too weak when callers still inspect the hidden representation.
-It is too broad when unrelated policy or lifecycle decisions are bundled behind
-one name. It is speculative when no representative case needs the boundary.
-
-## Representative Cases And Checks
-
-Choose cases before implementation shape hardens. Include only cases that
-distinguish meaningful behavior:
-
-- a normal case;
-- each relevant data variant;
-- a boundary or absence/default case;
-- a forbidden or impossible case;
-- a product-meaning case that a mechanically plausible implementation could
-  get wrong.
-
-Map cases to evidence. Unit examples are not always enough: a type, contract,
-property check, runtime validation, state-transition check, UI inspection, or
-human acceptance may carry the guarantee more directly.
-
-## Deferred Abstractions
-
-Separate three things:
-
-1. design artifacts needed to understand the current change;
-2. implementation items needed to make the accepted behavior real;
-3. abstraction candidates that the sketch noticed but current evidence has not
-   earned.
-
-For each deferred candidate, state the pressure that would reopen it. Do not
-promote it merely because the wished top level uses a convenient name.
-
-## Failure Checks
-
-A sketch is too shallow when:
-
-- it can be reduced to "edit these files" without losing information;
-- the data definition is a type name with no valid/excluded members;
-- the template does not mirror the important variants or traversal shape;
-- wished helpers expose no caller contract or hidden detail;
-- the top level speaks in framework or storage vocabulary;
-- examples all follow the happy path;
-- checks prove execution but not the accepted meaning;
-- deferred ideas silently enter the implementation queue.
-
-Return to product clarification or modeling when the purpose, valid members, or
-case outcomes cannot be stated without guessing.
-
-## Compact Example
-
-For a form-to-domain conversion, do not begin with `add mapper.ts`.
-
-```text
-Purpose: convert editable form state into valid schedule content.
-Data variants: one-time | recurring; optional end date; local date/time input.
-Cases: one-time, recurring without end, recurring with end, invalid interval.
-Template: branch by schedule kind, normalize shared time fields, validate the
-variant, construct domain content.
-Wishful top level: validate(form) -> normalize(form) -> makeScheduleContent(...)
-Barrier: makeScheduleContent hides the domain representation and rejects
-impossible combinations.
-Checks: one table row per meaningful variant and forbidden combination.
-```
-
-The concrete functions may change after repository inspection. The design
-pressure should remain stable.
-
-## Conceptual Lineage
-
-This reference adapts procedural abstraction, data abstraction, wishful
-thinking, and abstraction barriers from Abelson and Sussman's *Structure and
-Interpretation of Computer Programs*, together with the data-directed design
-recipe from Felleisen, Findler, Flatt, and Krishnamurthi's *How to Design
-Programs*. It uses those ideas as design judgment, not as a mandatory phase
-sequence.
-
-- SICP: https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book.html
-- HtDP: https://htdp.org/2026-5-28/Book/index.html