@hobin/developer 0.1.0

package/skills/model/references/problem-modeling.md

@@ -0,0 +1,262 @@
+# Problem Modeling Reference
+
+Use this reference when condition modeling needs more than a light invariant.
+
+This reference models conditions only. It does not choose capability routing or
+task ownership.
+
+## Contents
+
+- Core Question
+- Requirement Normalization
+- Lens Selection
+- Problem Shape Router
+- Modeling Tool Selection
+- Modeling Rules
+- Guarantee Placement
+- Common Failure Signals
+- Verification Target Derivation
+- Stop Checks
+- AI Delegation Boundary
+
+## Core Question
+
+Model the condition space under judgment:
+
+```text
+What facts, rules, constraints, forbidden cases, transitions, and objectives must
+be true for any acceptable solution?
+```
+
+Do not model the whole real-world domain. Include only the facts that affect the
+current invariant, product decision, or verification target.
+
+## Requirement Normalization
+
+When starting from natural language, lower the prose into condition-space parts
+before choosing a modeling tool:
+
+```text
+1. Nouns become domain facts: user, document, cart, item, order, state, event.
+2. Actions and judgments become predicates: canEdit, canCheckout, isValidTransition.
+3. Quantity words become quantifiers: all, at least one, none, exactly one, at most one.
+4. Conditional words become implication: if, only if, unless, whenever.
+5. Implications become counterexamples: P => Q means the failure shape is P && !Q.
+6. Finite policy combinations become decision spaces.
+7. Time words become transition or temporal questions.
+8. Unspecified domain choices become open policy questions.
+```
+
+Do not skip this step when a requirement contains words such as valid, ready,
+allowed, all, any, never, always, unless, only if, after, retry, or timeout.
+Those words are often the actual problem.
+
+## Lens Selection
+
+Use multiple lenses when the task mixes concerns.
+
+| Lens | Use when | Output emphasis |
+| --- | --- | --- |
+| `predicate-logic` | hidden booleans, quantifiers, implication, rewrite/equivalence questions | predicates, domains, counterexamples, equivalence risks |
+| `test-specification` | tests should express behavior, structural properties, or metamorphic relations | examples, properties, generators, counterexamples |
+| `contract-property` | function/API behavior, caller/callee boundaries, valid inputs | preconditions, postconditions, invariants |
+| `equation-invariant` | a compact formula, precedence rule, or conserved relationship is clearer than rows | formula, invariant, counterexample shape |
+| `proof-invariant` | proof, loop correctness, or preservation across steps matters | loop invariant, proof obligation, termination condition |
+| `data-relation` | data facts, queries, constraints, or representation replacement matter | relations, joins, violation queries, schema/model compatibility |
+| `absence-default-semantics` | configurable, optional, nullable, defaulted, persisted, or externally supplied values may be missing | valid members, absence meanings, default owner, legacy shape, misplaced-default counterexample |
+| `decision-space` | finite policy/case matrix, role/status/flag combinations | inputs, finite partitions, outputs, missing/conflicting cases |
+| `domain-relation` | entities and relationships drive behavior | entities, relations, assumptions, properties |
+| `transition-temporal` | state changes, async flows, retries, workers, lifecycle | states, actions, safety, liveness, stale events |
+| `constraint-objective` | assignment, optimization, configuration, solver-like work | variables, constraints, objective, invalid representations |
+| `logic-programming` | facts and rules should be queried directly or recursively | facts, rules, queries, possible worlds |
+| `ai-delegation` | preparing a clear task for another agent or skill | facts, rules, forbidden cases, objective, verification |
+
+## Problem Shape Router
+
+Choose the first representation from the shape of uncertainty, not from tool
+preference.
+
+| Problem shape | Start with | Why |
+| --- | --- | --- |
+| A boolean name feels vague: valid, ready, allowed, safe, complete | `predicate-naming` | Forces the domain question behind the boolean to be explicit |
+| The rule says all, any, none, at least one, exactly one, or at most one | `set-quantifier-model` | Separates the domain set from the required count |
+| The rule is conditional: if, only if, unless, whenever | `implication-counterexample` | Turns a policy into the failure shape to exclude |
+| A refactor, rewrite, schema change, or optimization must preserve meaning | `rewrite-equivalence-check` or `replacement-schema-model` | Separates logical equivalence from language/runtime semantics |
+| A fact must remain true across calls, steps, data mutations, or loops | `equation-invariant`, `contract-model`, or `loop-invariant-proof` | Names the preserved guarantee before choosing a representation or change |
+| Role/status/flag/action combinations are finite and reviewable | `decision-table` | Finds missing and conflicting cases |
+| Facts and relationships drive correctness | `domain-model`, `relational-query`, or `data-constraint` | Makes possible instances and impossible fact combinations visible |
+| Correctness depends on movement through time | `state-transition` or `temporal-model` | Distinguishes valid snapshots from valid behavior |
+| The task is to find a satisfying value, allocation, plan, or counterexample | `constraint-objective`, `smt-counterexample`, or `logic-programming` | Models the conditions a solution must satisfy |
+| The answer depends on stakeholder policy | `human-decision-surface` | Prevents the model from inventing product meaning |
+
+## Modeling Tool Selection
+
+Select tools after selecting lenses. A lens says what to look for; a tool says
+how to represent the condition space. Use the full modeling range, not only
+decision tables or solvers.
+
+| Tool | Use when | Do not use when |
+| --- | --- | --- |
+| `predicate-naming` | important booleans hide product meaning | sequence, data relationships, or optimization are the main issue |
+| `set-quantifier-model` | rules use all, any, none, at least one, exactly one | the domain cannot be stated |
+| `implication-counterexample` | a rule is conditional: if P then Q | no useful `P && !Q` failure case exists |
+| `rewrite-equivalence-check` | refactoring conditionals, predicates, sets, or quantifiers | language semantics, side effects, evaluation order, or runtime representation changes meaning |
+| `example-test-spec` | concrete scenarios define required behavior | examples are arbitrary and miss the intended property |
+| `structural-property-test` | behavior has a general property over many valid inputs | valid input generation or property definition is unclear |
+| `metamorphic-relation` | exact output is hard to know but related runs should agree | no meaningful relation exists between transformed inputs |
+| `contract-model` | the risk is at a function/API/component boundary | the main issue is stakeholder policy over many cases |
+| `type-representation-model` | invalid states can be excluded or exposed by data shape | the language cannot express the semantic guarantee |
+| `loop-invariant-proof` | correctness depends on every loop or proof step preserving a fact | tests provide enough evidence for the risk |
+| `relational-query` | facts are best modeled as relations, joins, projections | behavior is mainly local branching |
+| `data-constraint` | schema, uniqueness, existence, or update constraints matter | the rule is purely transient UI behavior |
+| `replacement-schema-model` | changing schema/API/representation must preserve old meaning | no old abstract model must be recovered |
+| `absence-default-model` | a value can be omitted, null, empty, defaulted, inherited, hydrated, or supplied by another boundary | the value is always required and has no legacy or external shape |
+| `decision-table` | independent inputs can be partitioned into finite buckets and mapped to outputs/actions | inputs depend strongly on each other, side effects dominate, a loop/recursion is required, inputs are unbounded lists/complex types, or the table is too large |
+| `equation-invariant` | a formula, precedence rule, or always-true relationship is clearer than enumerating rows | policy genuinely differs by many discrete buckets |
+| `domain-model` | entities, relations, possible instances, and properties matter | the task is a local transform with no domain ambiguity |
+| `state-transition` | a state can be valid but invalidly reached | current-state validity fully captures correctness |
+| `temporal-model` | concurrency, retry, timeout, stale event, fairness, or liveness matters | finite deterministic examples cover the risk |
+| `constraint-objective` | variables, hard constraints, and preferences must be separated | a bespoke algorithm is simple, fixed, and performance-critical |
+| `smt-counterexample` | satisfaction, contract, arithmetic, string, bitvector, or data-structure edge cases need counterexample search | the model cannot be encoded accurately enough |
+| `logic-programming` | facts, rules, recursive relations, or possible worlds are the program model | deterministic imperative control flow is simpler |
+| `human-decision-surface` | reasonable stakeholders could choose different policies | the answer follows from existing rules or data |
+| `ai-delegation-model` | another skill, tool, or agent needs a task contract | success criteria and verification cannot be stated |
+
+For decision tables, check the four fit questions before selecting the tool:
+
+```text
+1. Is there a clear map between independent inputs and outputs?
+2. Can the inputs be cleanly and concisely enumerated as finite partitions?
+3. Is a table clearer than prose, an equation, an invariant, or a state model?
+4. Will the table stay small enough to review?
+```
+
+If any answer is no, prefer another tool or split the model.
+
+When presenting selected tools to the user, explain each tool in plain terms:
+
+```text
+Tool:
+  What the tool means.
+Why this tool:
+  What shape of uncertainty or correctness risk it exposes.
+Not this tool when:
+  The boundary where another tool is more appropriate.
+Output:
+  What the tool should make visible: predicate, property, counterexample,
+  table row, transition, query, constraint, objective, or human decision.
+```
+
+## Modeling Rules
+
+- Normalize prose before solving. First identify domain facts, predicates,
+  quantifiers, implications, counterexamples, finite decision spaces, temporal
+  language, and open policy questions.
+- Separate meaning from implementation. Predicate names should say what is true,
+  not how it is computed.
+- Separate predicate roles. A decision predicate can be true or false; an
+  assumption or precondition defines when a property is meaningful; a property
+  is a guarantee that must not be false in valid states.
+- Separate assumptions from guarantees. Use assumptions for well-formedness,
+  preconditions, and product decisions that must be true before a property means
+  anything.
+- Treat `P => Q` as a failure condition: `P && !Q`.
+- For finite decisions, prefer explicit case coverage over prose, but only when
+  inputs form reviewable finite partitions.
+- Prefer an equation or invariant over a decision table when a compact
+  relationship communicates the rule more clearly.
+- For stateful behavior, distinguish current-state invariants from transition
+  rules over old and new state.
+- For optimization, distinguish constraints that must hold from objectives that
+  choose among valid solutions.
+- For optional, nullable, defaulted, persisted, configurable, or externally
+  supplied values, model absence before design. State valid members; whether
+  absent, `undefined`, `null`, empty, and false-like values differ; the default;
+  the owner of that default; the legacy shape; and the counterexample that
+  proves the default was enforced in the wrong layer.
+- Preserve domain-specific unknowns as questions. Do not answer them by
+  aesthetic preference or by over-formalizing.
+
+## Guarantee Placement
+
+For each property, choose the cheapest trustworthy layer that can carry the
+guarantee:
+
+- Use `type` when the language can exclude invalid states directly.
+- Use `contract` when the rule is semantic and must guide callers/callees.
+- Use `runtime-validation` when invalid external input must be rejected.
+- Use `assertion` when an internal state must already be guaranteed and cheap to
+  check.
+- Use `unit-test` or `integration-test` when behavior has concrete examples.
+- Use `property-test` when a domain generator can express the valid input set.
+- Use `proof`, `model-check`, or `solver` only when exhaustive reasoning or
+  counterexample search is worth the modeling cost.
+- Use `human` when the rule is a product decision, not a derivable fact.
+- Use an explicit default or normalization owner when missing or legacy data
+  should be translated into a domain value before consumers rely on it.
+
+If the chosen layer is not a test, still create a verification target explaining
+what evidence will prove the guarantee.
+
+## Common Failure Signals
+
+- A natural-language `and/or` requirement has no explicit grouping.
+- A rule uses "all", "any", "never", "always", "at least one", or "exactly one"
+  without a domain.
+- A quantifier can be read in more than one order, such as "some resource all
+  users can access" versus "each user can access some resource."
+- A predicate mixes decision, assumption, and property roles.
+- A type accepts values outside the valid domain, but there is no validation or
+  precondition.
+- A fallback expression silently becomes the owner of product or domain default
+  policy.
+- A default value appears in multiple layers without one explicit owner.
+- A decision table is complete internally but may not be correct product policy.
+- A state enum exists, but allowed transitions are not represented.
+- A representation change loses information needed to reconstruct the old model.
+- An AI task prompt gives procedure but not facts, constraints, objective, or
+  verification.
+
+## Verification Target Derivation
+
+Turn model elements into verification targets:
+
+- `predicate`: unit test, property test, contract check, or proof obligation.
+- `forbiddenCase`: negative test, runtime validation, type exclusion, or model
+  check.
+- `decisionSpace`: case matrix, table validation, branch coverage by meaning.
+- `stateTransition`: transition tests, temporal model, stale event checks.
+- `constraint`: assertion, database constraint, validation, solver check.
+- `absenceDefault`: legacy/missing-value case, normalization contract, creation
+  default, serialization round trip, and consumer fallback boundary.
+- `objective`: ranking/optimization evidence and accepted tradeoff.
+- `openQuestion`: human decision before any action that depends on it, or
+  explicit acceptance of the uncertainty.
+
+## Stop Checks
+
+Before treating the model as usable, confirm:
+
+- Each important boolean names a domain question, not an implementation trick.
+- Each rule has a domain: the values, states, entities, or transitions it talks
+  about.
+- Quantifiers have a clear scope and order.
+- Conditional rules have a counterexample shape.
+- Decision predicates, assumptions, and properties are not collapsed into one
+  vague predicate.
+- The selected tool explains the uncertainty it exposes.
+- Each guarantee has an owner and an evidence target.
+- Human policy choices remain open questions instead of guessed rules.
+
+## AI Delegation Boundary
+
+When delegating to an AI helper, sub-agent, or specialized skill, do not provide
+only a procedure. Provide:
+
+- context: where the work lives;
+- variables/concepts: relevant entities, states, and predicates;
+- constraints: must-hold rules and forbidden cases;
+- objective: what to optimize or preserve;
+- verification: counterexamples, gates, and accepted evidence.
+
+AI helpers are not solvers. Their output must still be checked against the model.

package/skills/naming-judgment/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: naming-judgment
+description: "Review or create code names by separating stable domain meaning from the current implementation. Use when variables, functions, types, modules, components, APIs, fields, or abstractions are generic, misleading, filler-like, implementation-shaped, or carrying multiple product senses."
+---
+
+# Naming Judgment
+
+Choose names that preserve domain sense across implementation change.
+
+## Core Question
+
+What domain sense should this name expose, what detail should it hide, and what
+change boundary should it preserve?
+
+## Inputs
+
+- Current name and the code or artifact it identifies
+- Nearby callers, callees, tests, and module context
+- Product vocabulary, invariant, or model when available
+- Audience: local helper, cross-module API, UI domain code, or integration
+
+## Output
+
+Lead with the user's product language; keep naming theory secondary.
+Produce the naming pressure, current sense, hidden or overexposed detail,
+failure mode, proposed name or placement move, affected scope, and intentionally
+deferred names. When used inside a larger task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: the proposed name or boundary move and the sense it preserves
+Basis: callers, behavior, domain vocabulary, and conventions
+Open questions: unresolved domain meaning or boundary pressure, or none
+Artifacts: rename map and affected scope
+```
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when a reader can rely on the name's sense without inspecting the current
+implementation, and the name neither admits invalid uses nor freezes incidental
+detail. Revisit when callers, product vocabulary, or the named boundary changes.
+
+## Method
+
+1. Read nearby callers and callees before judging the word.
+2. Identify the audience and the named thing's role.
+3. Separate stable sense from current referent.
+4. Classify the failure: overly general, overly specific, filler action, verb
+   mismatch, false abstraction, or sense collision.
+5. Choose a name shape appropriate to data, pure transformation, side effect,
+   predicate, event glue, or public API.
+6. Use module placement to supply context when an honest local name becomes too
+   long, but do not invent a module solely to shorten a name.
+7. Before editing, state: `<old> says <X>, but callers rely on <Y>`.
+8. Bound an accepted rename as a mechanical follow-up and identify the callers
+   and tests that must be verified.
+
+## Missing Evidence
+
+Return `needs-evidence` when callers or domain language can reveal the intended
+sense. Return `blocked` when only a product owner can decide the concept. Return
+`not-applicable` when the apparent naming problem is actually a model or design
+problem.
+
+## Boundary
+
+Do not implement the rename, promote a new abstraction, invent product meaning,
+rename external conventions, or replace every short name with a longer one.
+Reuse does not prove that a generic name is sound.
+
+## References
+
+Read [the naming reference](references/elements-of-clojure-naming.md) for
+subtle, disputed, or recurring naming pressure.

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

@@ -0,0 +1,74 @@
+# 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/schedule/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: schedule
+description: "Decide whether a concrete structural change or reviewed abstraction candidate belongs now, after, or never using invariant pressure, evidence, reversibility, nested-work pressure, and cost of delay. Use when the candidate is concrete and the consequential question is timing."
+---
+
+# Schedule
+
+Decide when a concrete structural move belongs.
+
+## Core Question
+
+When should this candidate be done: now, after, or never?
+
+## Inputs
+
+- Concrete candidate and scope
+- Evidence and accepted contract when available
+- Current invariant pressure and nested-work pressure
+- Reversibility, cost of delay, risk if done now, and risk if delayed
+
+## Output
+
+Lead with the user's current risk and cost of delay; keep timing labels secondary.
+Produce `now`, `after`, or `never` with rationale, evidence, invariant pressure,
+risks, and a reopen condition for deferred work. When used inside a larger task,
+return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: now, after, or never with the decisive reason
+Basis: candidate, evidence, current pressure, reversibility, and delay cost
+Open questions: missing timing evidence, or none
+Artifacts: timing decision and reopen condition
+```
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when the current timing decision follows from observable pressure and
+deferred work has a concrete reopen condition. Revisit only when that condition,
+the invariant, reversibility, or cost of delay changes.
+
+## Method
+
+1. Restate the smallest concrete candidate and scope.
+2. Ask whether the current invariant or accepted implementation is blocked
+   without it.
+3. Check whether the candidate is evidence-backed and stable enough to act on.
+4. Compare the guarantee gained with the freedom and implementation paths lost.
+5. Consider nested-work growth, reversibility, and cost of delay.
+6. Decide:
+   - `now`: required to protect the invariant or unblock accepted work;
+   - `after`: useful but not required now;
+   - `never`: speculative, harmful, or outside this scope.
+7. For `after`, state evidence that should reopen the decision. For `never`,
+   state whether any scope change could make it relevant.
+
+## Missing Evidence
+
+Return `not-applicable` when no concrete candidate exists. Return
+`needs-evidence` when the candidate exists but present pressure or reversibility
+cannot be assessed. Return `blocked` when timing depends on a human-owned
+priority or risk choice that cannot be inferred. Bias away from `now` when
+evidence is thin.
+
+## Boundary
+
+Do not discover a signal, form or review the abstraction, implement the change,
+prioritize unrelated product work, or verify the final result.

package/skills/signal/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: signal
+description: "Inspect requirements, code, diffs, tests, UI states, names, or recent changes for observable structural movement and classify it as absent, horizontal, vertical, or ambiguous. Use when evidence suggests duplication, model-code mismatch, boundary pressure, or an emerging refactoring candidate."
+---
+
+# Signal
+
+Observe structural movement without promoting or scheduling it.
+
+## Core Question
+
+What structural movement is actually visible in the evidence?
+
+## Inputs
+
+- Requirement, code slice, diff, tests, command output, or UI state
+- Selected comparable artifacts
+- Invariant or condition model when available
+- Known callers when shared helpers, APIs, or boundaries are involved
+
+## Output
+
+Lead with the observed code or product pressure; keep signal labels secondary.
+Produce a judgment of `no-signal`, `horizontal`, `vertical`, or `ambiguous`,
+with confidence, evidence, selected comparison, smallest meaningful difference,
+smallest behavior-preserving movement, model-code mismatch, and a concrete
+review candidate only when vertical or ambiguous. When used inside a larger
+task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: observed structural movement and confidence
+Basis: selected artifacts, differences, callers, and model evidence
+Open questions: stabilizing or rejecting evidence still needed, or none
+Artifacts: horizontal movement or concrete review candidate
+```
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when the smallest meaningful difference is visible and the evidence
+supports a structural classification or an explicit evidence gap. Revisit after
+a behavior-preserving change, new caller evidence, or a changed model reshapes
+the comparison.
+
+## Method
+
+1. State the observed change pressure.
+2. Select the two artifacts most alike by responsibility, vocabulary, state
+   transition, failure mode, model element, or user-visible outcome.
+3. Name their smallest meaningful difference.
+4. Identify the smallest behavior-preserving movement that would expose whether
+   the difference is incidental or meaningful.
+5. Keep same-level alignment horizontal. Similarity alone is not evidence for a
+   new abstraction.
+6. Classify movement as vertical only when a nameable concept, policy, boundary,
+   responsibility, or invariant remains after the difference is understood.
+7. Check model-code mismatches, hidden caller policy, duplicated defaults,
+   history, state, and misleading vocabulary.
+8. For vertical or ambiguous movement, state the candidate, pressure, hidden
+   detail, invariant risk, selected evidence, and evidence still needed.
+
+## Missing Evidence
+
+Return `needs-evidence` when another caller, comparison, diff, or model can
+change the classification. Return `not-applicable` when no structural movement
+is visible. Return `blocked` only when the relevant evidence cannot be accessed;
+otherwise keep product-meaning claims provisional when no accepted model exists.
+
+## Boundary
+
+Do not implement the movement, promote a candidate, decide timing, or turn
+horizontal similarity into a vertical abstraction.

package/skills/sketch/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sketch
+description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wishful top-level design, interfaces, checks, and a small implementation queue. Use when behavior is understood but ownership, boundaries, data flow, or implementation shape remains unresolved."
+---
+
+# Sketch
+
+Turn accepted intent into an implementable design surface.
+
+## Core Question
+
+What design surface makes this intent implementable?
+
+## Inputs
+
+- Requirement, invariant, or problem model when available
+- Existing code, API, data shape, UI flow, or failing behavior
+- Representative normal, boundary, forbidden, and product-meaning cases
+- Constraints and verification targets
+
+## Output
+
+Lead with the user's product language; keep design labels secondary.
+Produce purpose, relevant data definitions, representative cases, a template,
+wishful top level, wished interfaces, checks, a small implementation queue, and
+explicitly deferred abstractions. When used inside a larger task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: the smallest implementable design surface
+Basis: accepted intent, model, code, cases, and assumptions
+Open questions: unresolved design consequences, or none
+Artifacts: wished interfaces, checks, and implementation queue
+```
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when the first implementation item is small enough to execute and check,
+and non-local or invariant-bearing candidates are explicit rather than silently
+assumed. Revisit when implementation evidence breaks the ownership or data-flow
+assumptions.
+
+## Method
+
+1. Choose the strongest available source of intent and state its confidence.
+2. State the design unit's purpose in the user's language.
+3. Derive relevant data or state definitions and their ownership pressure.
+4. List representative cases before choosing code shape.
+5. Derive the template from data, state, traversal, or ownership flow.
+6. Write wishful top-level code, pseudocode, or interaction flow.
+7. For each wished interface, state its purpose, contract, owner, hidden detail,
+   and representative stop check.
+8. Separate design artifacts, implementation items, and deferred candidates.
+9. Keep the queue small; do not turn the sketch into a project plan.
+
+## Missing Evidence
+
+Return `needs-evidence` when repository inspection or representative cases can
+settle the design pressure. Return `blocked` when a product-owned choice would
+materially change the surface. Return `not-applicable` when the local
+implementation shape is already clear. Label all provisional design
+assumptions.
+
+## Boundary
+
+Do not own product scope, decide model correctness, promote an abstraction,
+schedule structural timing, implement the change, or verify completion.