architecture-refinement

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture refinement

Build and maintain a working theory connecting the domain problem, implementation,
evidence, and owner understanding. The purpose is better understanding and better
decisions, including discovering what ought to be built. Documents, tests, and
code support that purpose rather than measure success. Arrive at a design worth
defending, rather than defending the first design.

Use Peter Naur's [programming-as-theory-building perspective](https://gwern.net/doc/cs/algorithm/1985-naur.pdf):
understand how the program relates to its domain, justify its choices, and reason
constructively about modifications. Mitchell Hashimoto's whiteboard-defense
standard supplies a complementary ownership question: can the responsible owner
explain the shipped system's high-level behavior, choices, and limits? An
assistant-written specification or memorized explanation does not by itself
transfer that theory.

## When to use it

| Trigger | Review goal |
|---|---|
| Before consequential implementation | Challenge assumptions and identify what needs learning before committing to a design. |
| During implementation with uncertain requirements or surprising behavior | Use small experiments to develop the specification and implementation together. |
| Refining a technical issue | Separate the problem from an assumed cause or premature solution. |
| After a burst of AI-assisted implementation | Reconcile intended behavior with what actually emerged. |
| Lost understanding or an ownership handoff | Reconstruct the relevant model and recover architectural ownership. |
| Before shipping a significant change | Examine important assumptions, failure behavior, and evidence gaps. |
| An incident or surprising behavior | Revise the model using the counterexample, not merely patch the symptom. |

Use event-driven checkpoints and short learning loops within authorized work,
not a per-commit ritual or a mandatory approval for every experiment. Reconcile
at meaningful milestones before building another layer on uncertain assumptions.
Revisit settled choices when evidence, constraints, or consequences change; a
handoff may need explanation without redesign. Routine mechanical edits within
an already-understood design do not need this workflow.

## Choose the entry point and scope

- **Prospective:** refine a proposed architecture, implementation plan, or issue.
- **Exploratory:** use observations and small executable probes to learn the
  problem, semantics, and design while implementing within the authorized scope.
- **Retrospective:** reconstruct and critique an existing system, including
  vibecoded work whose behavior or complexity has outrun shared understanding.

Establish the user problem, known contracts and constraints, provisional success
criteria, and open questions. An incomplete specification can be the reason to
explore, not a reason to invent certainty or demand a complete plan. Bound the
work to a subsystem or user journey and its material dependencies. Distinguish
current behavior, desired behavior, and hypotheses; establish whether the task
authorizes investigation, review, implementation, or release assessment.

Scale effort to consequences. Isolated, disposable experiments favor speed;
customer data, credentials, shared infrastructure, or reliance on an output
create obligations even when the work is called a demo.

Use [project orientation](../project-orientation/SKILL.md) when conflicting or
unfamiliar context needs resolving. Domain skills and repository contracts supply
technical constraints; this workflow does not replace them. A review request
authorizes analysis and local drafts, not an unsolicited repair or rewrite.
Continue implementation when it is already within the user's authorized scope.

## Treat specification as a developing model

[Jay Kruer's argument about specification and verification costs](https://dank.systems/posts/2026-09-15-ai-bear.html)
highlights that implementation discoveries can reshape specifications and that
human oversight limits generated throughput. Apply that warning without assuming
all contracts are unknowable or all automation is ineffective.

Separate accepted commitments from provisional choices. Security, data integrity,
compatibility, and user-imposed constraints remain binding; implementation guesses
and open semantics are revisable. Learn enough to make the next safe move, then
update the working specification as evidence arrives. If discovery conflicts with
an accepted commitment, surface the conflict and obtain approval for a change;
do not silently redefine success to fit the implementation.

Use formal specifications, existing validators, and domain oracles where they fit
the risk and are available. A harness can preserve experiments, exercise checks,
and expose counterexamples; it cannot by itself establish that its objective,
fixtures, or oracle express the right problem. Additional generated specifications,
tests, or reviewers may share the same mistaken assumption.

## Clarify intent when drift is likely

Pause affected work before consequential analysis, execution, or edits when
intent has materially different plausible readings. Also pause when accepted
constraints conflict or a correction exposes an unresolved assumption.
A material difference changes the public contract, ownership boundary, scope,
execution conditions, or evidence needed to accept the result.

Use bounded inspection and safe probes to resolve factual gaps without committing
to an interpretation. Stay within authorized scope and preserve user data.
Source code can show what exists. Passing tests can show observed behavior.
Neither establishes what the owner intends. Distinguish these roles when an
example affects the choice:

- **Analogy:** transfer a named property. Other details can be incidental.
- **Acceptance case:** the stated case must work under its stated conditions.
- **Constraint:** preserve a binding condition across proposed solutions.

Ask one focused question about the unresolved choice. State the alternative
interpretations and the consequence of each. Offer concrete alternatives and a
reasoned recommendation. Make disagreement easy. The recommendation is not approval.

For example:

> Does “declarative FFI” mean manually declared signatures or bindings derived
> from module metadata? This changes who maintains the signatures. I recommend
> derived bindings if the metadata supplies the required types. Which do you want?

Wait for an answer that resolves the choice or explicitly delegates it within
accepted constraints. A generic “continue” does not settle an unresolved choice.
If the owner is unavailable, report the pending decision and keep affected work
paused. Independent safe investigation can continue. After resolution, state the
accepted property and its verification condition briefly, then take a bounded step.

Proceed without a question when accepted decisions or explicit delegation settle
the choice. Routine work with no material intent fork also proceeds. Words such
as “native,” “principled,” or “like this example” are not automatic triggers.
Revisit settled decisions only when evidence, changed constraints, or corrections
invalidate their premises. Obtain approval before changing an accepted commitment.

From sounkou-bioinfo/pi-skills, MIT.

More from sounkou-bioinfo/pi-skills