@hobin/developer 0.1.1 → 0.1.2

package/skills/sketch/references/composition-generative-recursion-and-accumulators.md

@@ -0,0 +1,196 @@
+# Composition, Generative Recursion, And Accumulators
+
+Use this reference after the base data recipe when structure alone does not
+finish the design. It distinguishes four moves that are often blurred together:
+designing an auxiliary, abstracting completed designs, generating new
+subproblems, and remembering knowledge that traversal would otherwise lose.
+
+## Design By Composition
+
+Write a wishful top level before helper bodies:
+
+```text
+publishableTasks(tasks):
+  return sortByPriority(onlyReady(normalize(tasks)))
+```
+
+For each wished operation, run the full small recipe:
+
+```text
+purpose: what subproblem it solves
+contract: input and output meanings
+examples: representative success and boundary cases
+template: derived from its data
+reason: why it is a distinct subproblem
+```
+
+An auxiliary is earned when it solves a separate domain subproblem, processes a
+referenced data definition, or generalizes a problem that the direct design
+exposes. “The original function is long” is not an independent purpose.
+
+## Abstraction From Completed Examples
+
+Start with at least two correct concrete designs that share a template.
+
+```text
+sum(numbers):
+  Empty -> 0
+  Node(first, rest) -> first + sum(rest)
+
+allReady(tasks):
+  Empty -> true
+  Node(first, rest) -> first.ready && allReady(rest)
+```
+
+Align corresponding positions:
+
+| Role | `sum` | `allReady` |
+| --- | --- | --- |
+| base | `0` | `true` |
+| item projection | identity | `task.ready` |
+| combine | `+` | `&&` |
+
+Only now is a fold-shaped candidate visible:
+
+```text
+fold(sequence, base, project, combine)
+```
+
+The shared template is evidence, not approval. Check that the roles have stable
+meaning, old functions become simple calls, process/cost does not accidentally
+change, and one realistic new case fits without adding flags. `abstraction-review`
+owns the promotion decision.
+
+## Structural Versus Generative Recursion
+
+Structural recursion consumes pieces selected directly from the input data
+definition. Generative recursion creates a new problem by domain knowledge.
+
+```text
+structural: totalEstimate(rest)
+  // rest is a field in Node(Task, Tasks)
+
+generative: binarySearch(sorted, lower, midpoint - 1)
+  // the next interval is calculated, not selected from a data field
+```
+
+Misclassifying the second as structural hides the algorithm idea and its
+termination obligation.
+
+## Generative Recursion Recipe
+
+Answer four questions before the body:
+
+```text
+trivial: which problems have a direct answer?
+generate: how are new subproblems produced?
+solve/combine: how do recursive answers form this answer?
+terminate: why do generated problems approach a trivial case?
+```
+
+Worked binary-search sketch:
+
+```text
+search(sorted, target, low, high):
+  if low > high:
+    return NotFound                    // trivial
+
+  mid = floor((low + high) / 2)        // generation knowledge
+  if sorted[mid] == target:
+    return Found(mid)                  // trivial
+  if target < sorted[mid]:
+    return search(sorted, target, low, mid - 1)
+  return search(sorted, target, mid + 1, high)
+```
+
+Process examples must show generated intervals:
+
+```text
+[0, 6] -> [4, 6] -> [4, 4] -> Found(4)
+[0, 0] -> [1, 0] -> NotFound
+```
+
+Termination measure: `high - low + 1` is a natural number for non-trivial
+calls, and each recursive call strictly decreases it. If no decreasing measure
+is known, state the possible non-termination boundary rather than asserting
+that the input “gets smaller.”
+
+## Accumulator Recipe
+
+Do not begin by adding an extra parameter. First identify the lost knowledge or
+repeated work in a conventional design.
+
+Example pressure: repeatedly appending to the end while reversing a sequence
+reprocesses prior results. Introduce `seenReversed` with an invariant:
+
+```text
+original == reverse(seenReversed) ++ remaining
+```
+
+Trace the relation:
+
+```text
+original [a,b,c], remaining [a,b,c], seenReversed []
+original [a,b,c], remaining [b,c],   seenReversed [a]
+original [a,b,c], remaining [c],     seenReversed [b,a]
+original [a,b,c], remaining [],      seenReversed [c,b,a]
+```
+
+The invariant determines initialization, update, and result:
+
+```text
+reverse(items):
+  loop(remaining, seenReversed):
+    Empty -> seenReversed
+    Node(first, rest) -> loop(rest, prepend(first, seenReversed))
+  return loop(items, Empty)
+```
+
+Check the invariant at three points:
+
+1. initialization relates the original input to the initial accumulator;
+2. one transition preserves the relationship;
+3. the base case plus the invariant implies the promised result.
+
+Different invariants create different algorithms. Choose the simplest invariant
+that solves observed pressure; an accumulator with no stated meaning is hidden
+state.
+
+## Iterative Refinement
+
+When a required case cannot be expressed or a forbidden case remains possible,
+change the data definition and propagate the change through:
+
+```text
+data examples
+-> behavior examples
+-> templates
+-> implementations
+-> tests
+-> serialized/public compatibility surfaces
+```
+
+A local type edit is incomplete when old persisted forms or callers remain in
+circulation.
+
+## Failure Diagnosis
+
+| Symptom | Repair |
+| --- | --- |
+| wished helper has no examples or independent purpose | inline it or run its own recipe |
+| abstraction is derived from one function | complete another concrete design first |
+| abstract parameters are implementation fragments | restate stable variation roles |
+| generated recursive call lacks an algorithm idea | return to structural template or state generation rule |
+| termination says only “smaller” | provide a well-founded measure or explicit divergence boundary |
+| accumulator is added for style | show lost knowledge, repeated work, or process pressure |
+| accumulator update is guessed | derive it from the invariant |
+
+## Source Trace
+
+- [*How to Design Programs*, official living edition](https://htdp.org/2026-5-28/Book/index.html):
+  design by composition, abstraction from concrete functions, generative
+  recursion and termination, accumulators and invariants, and iterative
+  refinement.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
+  wishful procedure decomposition, higher-order abstraction, and process shape.

package/skills/sketch/references/data-driven-design.md

@@ -0,0 +1,177 @@
+# Data-Driven Design
+
+Use this reference when product information should determine the program shape.
+The central insight is concrete: **a data definition is a construction rule for
+valid values, and that same rule determines the first honest function
+template**. Code shape should not be guessed from framework files or a favorite
+pattern when the cases are already present in the data.
+
+## The Six-Artifact Recipe
+
+Produce these artifacts in order. Each one catches a different error.
+
+```text
+1. data definition + interpretation
+2. representative data examples
+3. signature + purpose + executable stub
+4. behavior examples
+5. template derived only from the data definition
+6. completed function + checks
+```
+
+The order is diagnostic, not ceremonial. If the template has no branch for a
+required case, repair the data definition. If the template exposes all required
+ingredients but the result is wrong, repair the completed body. If no template
+ingredient can express the purpose, design an auxiliary with its own recipe.
+
+In an existing repository, recover the same artifacts from schemas, types,
+fixtures, callers, UI states, persistence, and tests. Do not copy pedagogical
+comments into production merely to imitate the recipe.
+
+## Complete Example: Let The Variants Write The Skeleton
+
+Requirement: show the customer-facing instruction for a fulfillment method.
+
+### 1. Define and interpret the data
+
+```text
+Fulfillment =
+  Pickup(storeId)       // collect from this store
+  | Delivery(address)   // send to this address
+  | Locker(lockerId)    // collect from this locker
+
+Excluded: a fulfillment value with none or several of these variants.
+```
+
+This is not merely a union type. Its interpretation says the three variants are
+different product meanings, so silently merging branches would lose policy.
+
+### 2. Construct one value from every clause
+
+```text
+Pickup("gangnam")
+Delivery("12 Teheran-ro")
+Locker("L-17")
+```
+
+If a valid example cannot be constructed, the definition is unusable. Add
+boundary examples when fields have their own restrictions.
+
+### 3. State what the function computes
+
+```text
+instruction : Fulfillment -> Text
+purpose: produce the instruction a customer should follow
+stub: instruction(method) = ""
+```
+
+The purpose says *what*, not “inspect the tag and branch.”
+
+### 4. Work behavior examples before implementation
+
+```text
+instruction(Pickup("gangnam"))
+  == "Pick up at gangnam"
+instruction(Delivery("12 Teheran-ro"))
+  == "Deliver to 12 Teheran-ro"
+instruction(Locker("L-17"))
+  == "Collect from locker L-17"
+```
+
+### 5. Derive, do not invent, the template
+
+One data clause becomes one branch. Fields in that clause become available
+ingredients.
+
+```text
+instruction(method):
+  match method:
+    Pickup(storeId)     -> ... storeId ...
+    Delivery(address)   -> ... address ...
+    Locker(lockerId)    -> ... lockerId ...
+```
+
+The strings and formatting policy do not come from the data shape; the purpose
+and examples supply them. The branch structure and accessible fields do.
+
+### 6. Complete and check
+
+```text
+instruction(method):
+  match method:
+    Pickup(storeId)     -> "Pick up at " + storeId
+    Delivery(address)   -> "Deliver to " + address
+    Locker(lockerId)    -> "Collect from locker " + lockerId
+```
+
+Run all three examples. Then try a fake fourth variant. A compiler failure or
+explicit missing branch reveals the exact extension point; a catch-all returning
+an empty string would hide it.
+
+## Select The Specific Recipe
+
+Read only the detail that matches the unresolved design question:
+
+| Evidence | Read | Expected artifact |
+| --- | --- | --- |
+| atomic values, intervals, itemizations, records, recursive or mutually recursive data, multiple complex inputs, complex outputs, or event loops | [Data-Shape Template Catalog](data-shape-template-catalog.md) | a template whose branches, selectors, recursive positions, and delegations correspond to the data definition |
+| wished helpers, several completed concrete functions, generated subproblems, termination uncertainty, repeated work, or lost traversal knowledge | [Composition, Generative Recursion, And Accumulators](composition-generative-recursion-and-accumulators.md) | separately designed auxiliaries, a justified abstraction, a generation template plus termination argument, or an accumulator invariant |
+
+These documents extend this recipe; they do not replace the six artifacts.
+
+## Existing-Code Recovery
+
+Use this recovery table rather than assuming the declared type is complete.
+
+| Artifact | Repository evidence | Typical contradiction |
+| --- | --- | --- |
+| data definition | schema, type, constructors, persisted samples | runtime contains a legacy or impossible-looking shape |
+| interpretation | product copy, callers, docs, analytics meaning | two same-shaped values mean different things |
+| data examples | fixtures, factories, production samples | only the happy variant has an example |
+| behavior examples | tests, screenshots, API examples | expected output encodes an undocumented default |
+| template | branches, selectors, traversal, delegation | catch-all hides a meaningful clause |
+| completed body | implementation | code needs information absent from the data model |
+
+When evidence conflicts, keep the contradiction visible. `model` owns disputed
+validity or policy; this reference shapes the implementable surface once the
+meaning is accepted.
+
+## Sketch Output
+
+```text
+Purpose: result in product language
+Data: valid clauses, interpretation, excluded values
+Data examples: at least one per clause and meaningful boundary
+Behavior examples: input -> expected result with rationale
+Template: branches, selectors, recursive calls, and delegations derived from data
+Wish list: separately designed subproblems
+Checks: examples, properties, boundaries, and compatibility evidence
+First item: smallest executable step implied by the template
+Deferred: abstractions or policies not yet earned
+```
+
+## Failure Diagnosis
+
+| Symptom | Return to |
+| --- | --- |
+| valid product case has no representation | data definition and interpretation |
+| data clause has no example | data examples |
+| tests describe traversal rather than result | purpose and behavior examples |
+| branch has no corresponding data clause | template derivation |
+| recursive call is on an arbitrary “smaller” value | structural versus generative recursion recipe |
+| helper has a body but no independent purpose | wish-list design |
+| abstraction precedes comparable completed designs | abstraction-from-examples recipe |
+| changed type ignores stored/public older forms | existing-code recovery and compatibility model |
+
+## Source Trace
+
+- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
+  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018,
+  and the [official living edition](https://htdp.org/2026-5-28/Book/index.html):
+  information analysis, data definitions and interpretations, examples,
+  signatures and purpose statements, templates, implementations, tests, and
+  iterative refinement.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
+  wishful decomposition and the distinction between procedure text and the
+  process it generates.

package/skills/sketch/references/data-shape-template-catalog.md

@@ -0,0 +1,241 @@
+# Data-Shape Template Catalog
+
+Use this catalog after the six-artifact recipe in
+[Data-Driven Design](data-driven-design.md). Its core rule is:
+
+```text
+data clause          -> function branch
+compound field       -> selector or destructured value
+self-reference       -> natural recursive call at that exact position
+reference to B       -> delegation to B's template at that exact position
+```
+
+The template inventories available ingredients. The purpose and examples decide
+how to combine them.
+
+## Atomic And Fixed-Size Data
+
+For an atomic value, the template contains the parameter and relevant domain
+constants. There is no structural decomposition to invent.
+
+```text
+Celsius = Number interpreted as a measured temperature
+
+alertLevel : Celsius -> Level
+alertLevel(celsius) = ... celsius ... FREEZE_POINT ... HEAT_LIMIT ...
+```
+
+Intervals add meaningful partitions only when behavior changes at their
+boundaries:
+
+```text
+alertLevel(celsius):
+  if celsius < 0        -> ...
+  else if celsius < 35  -> ...
+  else                  -> ...
+```
+
+Do not branch on arbitrary numeric ranges merely because a conditional is
+possible. Each range needs a product interpretation and boundary examples.
+
+## Itemizations And Enumerations
+
+For a finite set of alternatives, create one branch and one behavior example per
+meaningful clause. The complete fulfillment example in the parent reference is
+the canonical shape.
+
+Template:
+
+```text
+Result = Success(value) | Rejected(reason) | Retryable(delay)
+
+render(result):
+  match result:
+    Success(value)      -> ... value ...
+    Rejected(reason)    -> ... reason ...
+    Retryable(delay)    -> ... delay ...
+```
+
+Merge two clauses only when their product meaning, not merely their current body,
+is the same. A catch-all branch is suspicious when adding a variant should force
+a new decision.
+
+## Structures And Records
+
+A record groups a fixed natural whole. List only fields relevant to the purpose;
+the template is not permission to expose every stored field.
+
+```text
+Schedule = Schedule(start, end, timezone)
+
+duration(schedule):
+  ... schedule.start ... schedule.end ...
+```
+
+`timezone` remains absent because elapsed duration does not need it. If the
+function unexpectedly needs recurrence policy, either the purpose is broader
+than stated or the data definition lacks information.
+
+## Self-Referential Data
+
+A valid self-referential definition has at least one non-recursive clause from
+which values can be constructed and at least one recursive clause that creates
+larger values.
+
+```text
+Tasks = Empty | Node(Task, Tasks)
+interpretation: a finite ordered task sequence
+```
+
+Construct examples from the base outward:
+
+```text
+Empty
+Node(Task("review", 20), Empty)
+Node(Task("write", 40), Node(Task("review", 20), Empty))
+```
+
+For `totalEstimate`, derive the template mechanically:
+
+```text
+totalEstimate(tasks):
+  match tasks:
+    Empty -> ...
+    Node(first, rest) ->
+      ... first ... totalEstimate(rest) ...
+```
+
+Why that recursive call? The `Node` clause contains one `Tasks` field named
+`rest`; the template therefore contains one natural recursive call on `rest`.
+The completed function follows from examples:
+
+```text
+totalEstimate(tasks):
+  match tasks:
+    Empty -> 0
+    Node(first, rest) -> first.minutes + totalEstimate(rest)
+```
+
+Test at least two recursive layers. Recursing on `dropEveryOther(rest)` or a
+newly partitioned list is not structurally derived; use the generative-recursion
+recipe instead.
+
+## Mutually Referential Data
+
+When definitions refer to each other, derive a family of templates with a
+delegation wherever the reference occurs.
+
+```text
+Document = Document(List<Section>)
+Section  = Section(title, List<Block>, List<Section>)
+Block    = Paragraph(text) | Image(src)
+```
+
+For a word-count sketch:
+
+```text
+countDocument(document):
+  combine map(countSection, document.sections)
+
+countSection(section):
+  combine map(countBlock, section.blocks)
+          map(countSection, section.children)
+
+countBlock(block):
+  match block:
+    Paragraph(text) -> words(text)
+    Image(src)      -> 0
+```
+
+The reference graph, not convenience, determines the delegations. An oversized
+function with nested tags usually means the template family was collapsed.
+
+## Two Complex Inputs
+
+Do not automatically multiply every clause. Decide how the two values move.
+
+### One input controls
+
+`applyDiscounts(cart, rules)` traverses the cart while `rules` is constant or
+queried. Derive the traversal from `Cart`; treat `Rules` as domain knowledge.
+
+### Inputs move in lockstep
+
+`sameShape(leftTree, rightTree)` compares corresponding nodes. State the shape
+relation and branch on paired cases:
+
+```text
+(Leaf, Leaf)
+(Node, Node) -> recurse on corresponding children
+(Leaf, Node) or (Node, Leaf) -> false
+```
+
+### Inputs vary independently
+
+Collision policy between `UserRole` and `ResourceState` may need the meaningful
+cross-product or a decision table. Write all relevant combinations explicitly;
+do not hide them in nested defaults.
+
+The smell is not “two loops.” It is an unstated relationship between the input
+shapes.
+
+## Functions That Produce Complex Data
+
+The output definition constrains constructors just as the input definition
+constrains selectors.
+
+```text
+Notice = Info(text) | Warning(text) | Blocked(reason)
+
+classify(order):
+  ... -> Info(...)
+  ... -> Warning(...)
+  ... -> Blocked(...)
+```
+
+Work expected output values before choosing constructors. If several output
+variants are valid, the unresolved choice is policy, not implementation freedom.
+
+## Interactive Programs
+
+Define the world state before handlers:
+
+```text
+World = Editing(draft) | Saving(draft, requestId) | Failed(draft, reason)
+
+onEvent : World x Event -> World
+view    : World -> UI
+stop    : World -> Boolean
+```
+
+Then write event traces, not only snapshots:
+
+```text
+Editing("a") --Save--> Saving("a", 7)
+Saving("a", 7) --Saved(7)--> Editing("a")
+Saving("a", 7) --Saved(6)--> Saving("a", 7)   // stale response ignored
+```
+
+The handlers derive branches from both the world and event definitions. If
+correctness depends on history beyond `World`, refine the state or hand the
+temporal rule to `model`.
+
+## Diagnosis
+
+| Symptom | Likely repair |
+| --- | --- |
+| branch does not correspond to a data clause | remove it or repair the data definition |
+| selector is used outside its clause | restore the clause guard or use a better representation |
+| recursive call has no self-reference | classify as generative recursion or remove it |
+| self-reference has no recursive call | explain why that portion is intentionally ignored |
+| mutually referential logic is one giant conditional | derive one template per definition |
+| two complex inputs create accidental nested loops | state controlling, lockstep, or independent relation |
+| event handler cannot distinguish stale events | add identity/history to the world model |
+
+## Source Trace
+
+- [*How to Design Programs*, official living edition](https://htdp.org/2026-5-28/Book/index.html):
+  the recipes for atomic data, intervals, itemizations, structures,
+  self-referential and intertwined definitions, multiple complex inputs,
+  complex outputs, and world programs. The examples here are adapted to ordinary
+  product code and are not copied from the book.