iterate-design
Skill4 starsChanged 3 months agoMITView on GitHub
Pre-code design iteration for non-trivial features on markgate. Forces a design sketch with trade-offs before writing code, and guards against silent opinion-flipping when the user pushes back. Use when the user asks for an opinion ("what do you think?", "should we?", "recommended?"), proposes a new flag / env / config field, or raises a feature with multiple valid shapes. For the matching pre-push / done-declaration discipline (implementation anti-patterns, audit checklist, smoke-the-binary), see the companion `audit-before-done` skill.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- audit-before-doneSkill
- verify-e2eSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Ask for sign-off: Do not write code yet.
- Very specific: line 32
When the feature is an override, default to the markgate precedence:
- Distinctive: line 38
When the user pushes back, don't silently flip.
- Distinctive: line 42
If the new information actually changes that reasoning, say so explicitly: "this changes the calculation because X → Y → Z".
- Distinctive: line 44
If it doesn't, say that too: "the concern you raised still holds, because …".
- Distinctive: line 46
Never present an opinion as "it depends" unless it really does.
- Distinctive: line 69
Not a substitute for reading the code before proposing changes.
- Distinctive: line 70
Not a reason to over-consult the user on trivial decisions.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
iterate-design
A compact pre-code workflow for design-heavy work on markgate. Goal:
agree on the shape before any code is written, and don't drift on the
recommendation once taken. Implementation discipline and the
pre-push audit live in the companion skill audit-before-done.
The patterns this skill guards against:
- Jumping to implementation before the shape is agreed.
- Flipping recommendation based on user reframing without anchoring on the original reasoning.
Phase 1 — design sketch (before code)
Produce a short sketch the user can react to:
- Goal in one sentence. What problem, for whom.
- Options. 2–4 total. More than 4 causes paralysis. Each option gets a one-liner plus its main trade-off.
- Recommendation. Pick one. Say why, referring to the goal.
- Decisions that aren't obvious. Flag name, env var name, precedence chain, config field location, validation boundaries, where the docs need to change.
- Ask for sign-off. Do not write code yet.
When the feature is an override, default to the markgate precedence:
CLI flag > env var > .markgate.yml > default. Deviating needs
an explicit reason.
Phase 2 — hold the line
When the user pushes back, don't silently flip. Sequence:
- Restate why the original position was taken (the constraint, the past failure mode, the existing invariant).
- If the new information actually changes that reasoning, say so explicitly: "this changes the calculation because X → Y → Z".
- If it doesn't, say that too: "the concern you raised still holds, because …". Then address the sub-question.
- Never present an opinion as "it depends" unless it really does. Pick one and defend it.
Caution signs that you are drifting:
- Your previous message recommended A; this message recommends B with no new information cited.
- You labeled something "not recommended" without a concrete failure mode. Warnings without evidence are noise.
- You explained a failure mode as "the marker becomes stale" and stopped there. Finish the chain: "stale → verify returns 1 → check re-runs → the whole point of the feature is defeated."
Handoff
Once the user signs off on the sketch and you start writing code,
the audit-before-done skill takes over: implementation discipline
(no churn, no deletion on uncertainty), the widened audit
(grep every introduced name, check --help, smoke the built binary,
run make lint not just go vet), and the pre-push checklist.
What this skill is not
- Not a substitute for reading the code before proposing changes.
- Not a reason to over-consult the user on trivial decisions. If the change is one-line or obvious, just do it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

