pragmatic-design

Files (4)

• LICENSE
• SKILL.md
• THIRD-PARTY-LICENSE
• openai.yaml · agents/

SKILL.md (first lines)

# Pragmatic Design

Turn the request into a small implementation guide through focused investigation and consequential questions. Favor evidence, clear ownership of knowledge, and reversible choices. Finish with a guide; implement only when the user's request includes implementation.

## When not to run this

If the change has an obvious existing home (one module, an existing pattern, no new interface or dependency) and no consequential design decision, say so in a sentence and stop the design exercise. If the change is a handful of lines, make it and show the diff with its check; describing a three-line change takes longer than making it. No guide, no status line.

## Vocabulary

Use this self-contained subset of the `codebase-design` glossary. Do not load another skill merely for terminology or import its separate design rules.

- **Module:** an interface and its implementation, from a function to a tier-spanning slice.
- **Interface:** everything callers must know: types, invariants, ordering, errors, configuration, and performance obligations.
- **Implementation:** the code inside a module.
- **Seam:** a place where behavior can be altered without editing there; the location of an interface.
- **Adapter:** a concrete implementation satisfying an interface at a seam.
- **Depth:** behavior available relative to what callers must learn. **Leverage** is the capability callers gain; **locality** is the concentration of knowledge, changes, and verification.

Use interface for what callers must know and seam for where behavior varies. Do not substitute "component" or "boundary." Preserve actual project identifiers and domain names. Ownership means which module holds a business rule, not another structural type.

## 1. Investigate the requested flow

Trace the requested behavior from input to observable outcome. Inspect relevant callers, dependencies, interfaces, and checks, including affected sibling callers of shared functions. Find existing ownership and patterns before proposing structure.

Separate facts, assumptions, and unresolved decisions. Use requirements, recent bugs, and relevant history as evidence of change pressure; do not invent future requirements. For a new system, establish the use case and constraints instead.

Follow adjacent code only to answer a named question that could change the design. Stop when you can explain current behavior, locate the knowledge being changed, identify affected interfaces, and state the consequential unknowns. Do not survey the rest of the codebase. Reopen investigation only for a specific question raised by new evidence.

## 2. Resolve uncertainty with the user

A question is consequential when a different answer would change the owning module, the interface, or the approach. Everything else is a detail with a reversible default.

Answer factual questions through code and authoritative documentation first. Ask the user about consequential intent, priorities, and tradeoffs those sources cannot establish.

Ask one question at a time. Explain what decision it changes and recommend an answer with its reason. Use the answer to determine the next question; do not run a fixed questionnaire or seek approval for routine choices.

Resolve consequential choices before marking the guide ready. Continue independent work while awaiting an answer; silence is not acceptance. Stop asking once consequential choices are resolved and remaining details have defensible reversible defaults. Flag those defaults and what would require revisiting them; they do not block ready.

If no user is available (an agent-driven run) and a consequential choice is still open, finish everything that does not depend on it, mark the guide not ready, and list the question with your recommendation.

For technical uncertainty, name the question, evidence needed, and stopping condition. Choose the cheapest sufficient investigation:

- Code or documentation for existing facts.
- An explanation or acceptance scenario for unclear behavior.
- A diagram for ownership or flow; a wireframe for interaction.
- Disposable code when execution is needed to test feasibility, integration, or performance.

Difficulty explaining an approach identifies an open question, not proof of impossibility. Novelty or discomfort alone does not mandate a prototype. Resolve questions before committing to a structure they could invalidate. Use a prototype skill only if its capabilities fit the experiment. Do not promote disposable code into production without necessary hardening and verification.

## 3. Decide ownership and the first slice

Locate the knowledge, identify the owning module and its interface, trace effects on other modules, then choose the smallest useful end-to-end slice.

- Give each business rule an authoritative representation. Similar code encoding independent rules must remain independently changeable.
- Explain why each affected module changes. Multiple modules are not a failure: a feature can legitimately cross UI, domain logic, and persistence. Flag duplicated decisions and propagation into modules that should not need to understand them.
- Inspect reliance on another module's internals and unowned mutable state. Do not mechanically replace fluent calls or ordinary data transformations.
- Reuse existing modules and conventions unless evidence shows they obstruct the requested behavior or constraints. A new module needs a reason an existing one cannot give; mirroring an existing function is a reason to sit beside it, not to start a file.
- A business rule lives in the module named for its domain (a pricing rule in the pricing module), not in whichever caller first applied it, even while it has one caller. When consolidating duplicated knowledge, move it to that home and delete the other copies. Add nothing beyond that one home: no second helper, no constant or config for a value that does not change, no test you then skip.
- When the next change is unknown, choose the simplest reversible option. Do not invent extension points or configuration for hypothetical needs.

For new behavior, specify a tracer bullet: one narrow use case implemented through every required layer, with production obligations intact. Choose a slice that obtains feedback if the target is uncertain. Do not require it to settle every future seam. The first slice contains nothing that depends on an open decision, missing data, or a dependency that cannot be verified here; those go in a later slice, so the first one can be built and checked today.

For refactoring, identify the concrete problem and observable behavior to preserve. Reuse existing checks; add the smallest missing checks protecting affected states and failures. Do not impose a test count. Investigate testing difficulty before blaming the interface: infrastructure, external services, or nondeterminism may be responsible. Keep behavior-preserving changes distinguishable from intentional behavior changes.

Test-first development is optional unless requested or required by the project. Specify verification proportional to risk and honor required project checks.

## 4. Contain dependency knowledge

Explain each design-relevant dependency's purpose and which module owns integration. Reuse installed capabilities that meet the need.

Start with the owning module's interface. Contain dependency details there when exposing them forces unrelated callers to understand the integration. Add a separate adapter only for a concrete translation, isolation, or behavioral responsibility. Neither essentiality nor adapter count decides whether encapsulation earns its cost.

Keep framework-native types already used by the architecture unless the requested change reveals concrete coupling requiring translation. Do not wrap dependencies solely for hypothetical replacement. Prototype only integrations with an unresolved question requiring execution.

## 5. Present the implementation guide

Write a connected **Why → What → How** guide. Its length follows the number of consequential decisions, not the template: a change with one decision gets a paragraph and that decision; a feature crossing several modules gets about 300 words. Measure in words the reader spends, not lines. Omit sections that add no information. Never write more guide than the diff it describes deserves.

Before presenting, make one compression pass. State the first slice and whether it can be built now exactly once. Delete every repeated next-action, readiness, or status sentence; the Status line at the end is the only one. A decision that affects only a later slice is listed under that slice with its recommendation and never blocks the first. Keep every contract, obligation, and check; cut only prose.

**Why:** requested behavior or refactor objective, evidence, real constraints, and risks resolved or accepted. Label assumptions.

**What:** modules to change and the reason for each. For every created or changed interface, describe what callers must know. Include a concrete signature when types or calling convention are part of the decision. Identify dependencies and interactions being introduced or restricted. Flag open decisions, reversible defaults, and revisit conditions. Do not restate unchanged interfaces or produce method stubs.

**How:** first slice, verification, and feedback; later known slices in brief. Include pseudocode only for a non-obvious flow. State the next action appropriate to the user's request. Do not repeat slice order or pseudocode elsewhere.

End the guide with one line: `Status: ready` or `Status: not ready (open: <question>)`. Status describes the first slice: ready means it can be built and checked now. A consequential choice that only shapes a later slice is listed there and does not make the guide not ready. Flagged reversible defaults do not either. A choice that changes nothing the user's code does under either answer is a default, not a blocker: take it, flag it, stay ready.

For changed interfaces accepting untrusted input, accessing protected data, acquiring resources, or failing, specify the corresponding validation, authorization, cleanup, and failure obligations. Brevity does not excuse omitting them.

Every structural decision must follow from the request, constraints, or observed coupling. Reusing a module is a valid outcome. Do not fill a template with invented architecture.

## Lifecycle

After each implemented slice, update unresolved decisions and remaining work. Remove detail now represented by code; keep the guide while unfinished work still depends on it. Preserve durable rationale using the repository's existing documentation or ADR convention. Remove obsolete planning artifacts only after retaining useful rationale and respecting repository practice. The first merge does not automatically expire the guide.

From gafar123/the-simple-lazy-developer, MIT.

More from gafar123/the-simple-lazy-developer