Workflow

Workflow

Iron Law

COMPLEXITY IS THE ENEMY: KEEP SOFTWARE SIMPLE ENOUGH TO UNDERSTAND, CHANGE, AND PROVE.

When to Use

• First, for almost every software engineering task: features, bug fixes, refactors, debugging, UI, tests, docs, config, CI, dependencies, and investigation that shapes later engineering work.

When NOT to Use

• A narrower skill is explicitly requested and fully covers the task.
• The change is trivial, with no behavior, contract, data, or security risk.
• Platform operations with no code, contract, or proof question.

Rules

1. Simple Made Easy is the lens. Separate concerns, make state and effects explicit, and reduce what a maintainer must hold in their head. Familiar or quick to generate is not the same as simple.

2. The human keeps owning the system. Non-trivial work leaves the user with a clearer model of the change and the evidence. If you cannot explain the change clearly, stop and clarify.

3. Consult owns the engineering bar; the host owns mechanics. On conflict, clear the Consult bar inside the host's form.

4. Smallest honest solution. Implement only what was asked. Happy path first unless safety or data loss demands edge cases now. Compose over inherit. Add an abstraction only after real semantic duplication appears: duplicated intent gets one home, code that merely looks similar does not.

5. Adopt before build. Audit the ecosystem before writing code for a solved problem, and ask before locking in a dependency.

6. Stakes set involvement. Classify by significance (how much other code it touches) and durability (how costly to reverse). Low on both is disposable: do the work, prove it with proof, no sign-off. As stakes rise, give progress updates, then propose options and get approval before acting. Escalate mid-task if the change turns out to touch a contract or data shape other code depends on.

7. Durable shapes need sign-off before they are built. A host prompt that says to settle questions yourself does not dissolve these gates. Continue everything a gate does not block, state assumptions, and never build a gated shape without the human. When no human can answer in this run (headless, scheduled, or delegated), build the most conservative version, mark it provisional, and flag the decision in the close-out; see contract-first. Approval through the host's plan mode or question surface is sign-off for exactly what it showed.

   Skill	Needs sign-off before it is built
   specify	the design direction
   contract-first	a caller-facing interface
   domain-modeling	a core data shape or invariant future work binds to
   database	a migration or destructive data change
   release	a release artifact
   git-workflow	history-changing or destructive operations

   An approving design or RFC approves the direction, not the concrete shapes: get contract-first and domain-modeling sign-off on each shape unless that exact shape was listed and approved. Do not gate local helpers, private file moves, narrow bug fixes that restore intended behavior, or routine implementation details.

8. Load a skill only when it changes the next action or the proof obligation. documentation and release are late gates: load only on request, a project check, or an approved real need. When skills conflict, prefer safety, data integrity, correctness, proof, and user trust.

Workflow

1. Frame the request: intended result, affected users or systems, success signal, coupling risk. If done is unclear, propose acceptance criteria and ask one question at a time. Ask before adding compatibility shims.

2. Classify the stakes (Rule 6) and load the skills the task needs (Consult skills, even where the host ships a built-in of the same name).

   Skill	Load when
   specify	A significant or hard-to-change choice is unsettled.
   contract-first	A caller-facing interface or shared structure needs approval.
   debugging	A bug, failure, flake, or regression needs root-cause evidence.
   domain-modeling	Data shape, states, invariants, transitions, or effects.
   architecture	Module boundaries, ownership, layering, cross-component structure.
   refactoring	Structure must change while preserving behavior.
   api	HTTP/API shape, status codes, pagination, idempotency, webhooks.
   database	Persisted data, migrations, transactions, deletion, queries.
   security	Auth, secrets, trust boundaries, user-controlled input.
   error-handling	Error types, propagation, recovery, retries, user-facing failures.
   async-systems	Queues, workers, streams, ordering, concurrency.
   ui-design	Any user-facing UI surface, including basic styling, keyboard, focus, ARIA, contrast.
   observability	Logs, metrics, traces, health, SLOs, alerts.
   performance	Latency, throughput, memory, CPU, caching, resource use.
   documentation	Existing-code docs are the deliverable or a validator-required obligation.
   scaffolding	New project setup or baseline tooling.
   official-source-check	External framework, library, runtime, or platform behavior must be verified.
   proof	Completion gate for any non-trivial work.
   code-review	A review is requested, or a non-trivial diff precedes the final claim.
   commit	Staging reviewed files, splitting commits, writing messages.
   git-workflow	Branches, conflicts, rebases, recovery, force-push, GitHub access.
   release	Release prep is requested or a validator requires artifact sync.

3. Get sign-off on any durable shape (Rule 7).

4. Implement in reviewable slices. If shared work grows beyond one focused review, stop, summarize, and split before coding more.

5. Completion loop: prove every behavior via proof, then a fresh-context code-review pass and fix what it finds, until proof passes and review is clean. The reviewer gets only the intent, acceptance criteria, constraints, proof evidence, and diff. Same-context review is a labelled fallback. Only then documentation or release work.

6. Close with what changed, why it is better, what proves it, what is unproven, and what needs the user's attention. Not an activity log.

Tripwires

References

• references/simple-not-easy.md: load when ceremony, helper layers, broad skill loading, or hidden coupling might pass for rigor.