design-code-implement

Files (3)

• SKILL.md
• openai.yaml · agents/
• template.md · references/

SKILL.md (first lines)

# Design Code Implement

Decide *how* to build something whose *what* is already settled. Explore the repository's real architectural conventions with parallel sub-agents, surface where the new requirement is in tension with them, and offer at least three directions the user picks from.

This skill does not write production code. It ends when a direction is chosen and recorded.

## 1. Establish the input

Accept the requirement in whatever form it arrives: a file path, an upstream skill's handoff, or prose in the conversation. Never demand a file. Read what the user points to, and restate the requested outcome in one sentence; get it confirmed if it is at all ambiguous.

Do not ask the user for facts discoverable from the repository, runtime, or tools.

## 2. Scope the exploration

Decide the aspects yourself, from the requirement confirmed in §1. Do not send a scout sub-agent first, and do not ask the user to approve the aspect list — they cannot judge it before seeing the repository's reality, and a wrong aspect exposes itself in the reports.

Constraints on the aspect list:

- **Always include domain language**: what the existing concepts are called, and whether the requirement introduces a term the codebase does not have.
- **Architectural convention only**: how layers are cut, how errors travel upward, how data enters and leaves, where tests live, where the existing seams are. Exclude surface style — naming case, file placement, formatting. Linters and neighbouring code already teach those, and nobody picks a different implementation direction because of camelCase.
- **At most five sub-agents.** If the requirement seems to need more, merge aspects. A requirement genuinely spanning eight architectural aspects should be split before it is designed.
- **Bounded blast radius.** Explore only the areas the requirement touches, plus recent hotspots from `git log --oneline`. Do not sweep the whole repository; irrelevant conventions dilute the real tensions.

## 3. Dispatch and collect

Give every sub-agent the same tool preference:

- If a codebase knowledge-graph MCP is available, use it first; complete its indexing if the repository is not indexed yet.
- Otherwise prefer any other repository-aware navigation tool.
- Fall back to built-in search for string literals, configuration, scripts, and non-code files, or when the above return stale or inapplicable results.

Require every sub-agent to report exactly three things per finding:

1. **The existing convention** — what this repository already does for this aspect.
2. **The evidence** — file and line (`path/to/file.ts:42`). A claim without a path is not usable.
3. **The tension** — where the new requirement collides with that convention. If there is none, say so explicitly.

The tension field is the point of the exercise. Conventions with no tension are context; tensions are where directions come from.

## 4. Produce the directions

**If exploration found no existing convention for the requirement to inherit**, say so and stop; this skill has nothing to ground directions in. Do not produce directions.

Present **at least three** directions in the conversation, sequentially, so each is absorbed before the comparison.

- **Direction 1 is always the baseline**: follow every existing convention, open no new seam, take the most conservative path. It costs almost nothing to produce and it is what the other directions are measured against — without it the user cannot judge whether the extra cost is worth paying.
- **Directions 2 and 3 grow out of the reported tensions**, not from a template. Do not assign directions predetermined constraints; let the repository's actual friction decide where they diverge.

Give each direction exactly four fields:

1. **Positioning** — one sentence.
2. **Footprint** — which files and which seams it touches.
3. **Cost** — what it charges, concretely.
4. **When this is the wrong choice** — the condition under which this direction is a mistake.

The fourth field is mandatory and forces honesty. A direction with no failure condition has not been thought through.

Close with a **recommendation**: the direction you would pick and the tension or requirement that decides it. The choice stays the user's.

**When the tensions cannot support three real directions**, say so plainly: report that the existing conventions already determine the approach, and stop. Never pad the list with contrived variants — a user who cannot tell a real choice from a manufactured one stops trusting all of them.

**Mixing is allowed.** If the user wants one direction's overall shape with another's error handling, take it — then restate the combined direction in full and get it confirmed before writing anything. A mix understood differently by each side is worse than no mix.

## 5. Record the decision

Write `design.md`.

**Placement**: ask the user where it goes before writing it.

**Contents** — only what will be done, laid out as in [`references/template.md`](references/template.md):

- The chosen direction as diagrams, not prose.
  - Each flow that crosses components: an ASCII flowchart, one per trigger. Steps run top to bottom, numbered, each followed by an indented `↳` line naming the real function and file that does it. Leave the right side open, with only left-edge arrows and indentation, so wide characters never break alignment. Draw the success path only; under the diagram, list every failure the requirement implies as "step N fails → what happens". A step that is a flow of its own gets its own diagram, referenced as "→ Flow N".
  - Each entity that changes state: a Mermaid `stateDiagram-v2`.
  - Changes no diagram shows (migrations, configuration, interface shapes): a short list.
- The conventions this work must follow, one line each with its evidence path.
- Nothing else. **Do not write the rejected directions, and do not write their rationale.** A downstream implementing agent reads this file as instructions; describing an approach that is not being taken invites it to be taken.

**If `design.md` already exists**: read it first, then update it — carry forward whatever still holds. Never overwrite it unseen.

## 6. Hand back and stop

Report:

- The chosen direction in a short summary.
- The path to `design.md`.

Then stop. How and with what to implement is the user's call; do not start implementing or name a next command.

From GUOJIE-HONG/skills, MIT.

More from GUOJIE-HONG/skills