Solution Design - how a change fits, then decomposed, in one chat
The design carries the quality: a build handles the traps its plan named and ships the ones it missed. This is the single-chat form of the solution-designer seat - it works out where a feature belongs in the code you already have and breaks it into an ordered plan in this chat. It plans; the build step writes the code. The measurements behind these rules live in references/evidence.md - an audit appendix, not a run-time load.
Design mode - this chat, a read fan-out, or the designer seat
In this chat, ask the mode per references/design-mode.md - read it before designing; a mode the invocation or a calling flow already picked is inherited, never re-asked. Inside a designer seat: no ask, no dispatch - the dispatch is the answer, run the method below. A seat holds no AskUserQuestion, so each ask below is a report field there: an ambiguous brief returns NEEDS_CONTEXT (step 0), a behaviour change goes on the report's user_decisions: line (the Decisions ledger).
When to use / not
- Not for a change with an obvious single home - just make it.
- Not plan audit (
task-verify-plan) or built-code review (task-verify-code) - those come after.
The method - orient, judge, decompose
- Settle the ask first. Before you orient or design anything, load
habits-clarify (the Skill tool) and run it: an ambiguous, underspecified or multi-reading ask is settled with the user before the design starts, and its answers are the requirement the plan cites. A clear ask passes straight through. Inside a designer seat, load nothing here: an ambiguous brief returns NEEDS_CONTEXT naming the readings to settle.
- Orient from the project docs, don't re-derive them. Consult
<docs-path>/awareness/ARCHITECTURE-AWARENESS.md SCOPED, never whole: grep it for the modules the task touches plus a listing of <docs-path>/awareness/references/, then read the matching section ranges and the area's linked topic file. A docs.js where call only lists sections: read the ones it names (docs.js show, or the range) and cite that read, never the where. Absent that doc, take a bounded pass over the modules involved: a directory listing, then a file outline per file that matters, never a whole-file read. Either way Oriented: cites the EVIDENCE - the ranges read, the symbol calls made: the gate checks it against the session, and an orientation with no matching reads is a MAJOR finding. Read the preference docs that exist too (<docs-path>/preferences/: PERSONAL-CODE-PREFERENCES.md, ARCHITECTURE-PREFERENCES.md, PROJECT-CODE-PREFERENCES.md) and both assessments (<docs-path>/quality/: CODE-ASSESSMENT.md, ARCHITECTURE-ASSESSMENT.md) scoped to the task's modules - an entry is a lead, and no card adds a case of a weakness one records. A seam with a sibling repo: the related-projects awareness doc, already in context, names its far side.
- Load the house skill for the stack you're in, for its real trap list. Your project's convention rules auto-attach it the moment you touch a matching file; load it explicitly if you're designing before touching code. Carry the stack's real traps, not a generic checklist, and follow that skill's own routing to its specialist siblings (the stack -> skill map lives in the project's convention rules and router skills, not restated here).
- Judge the fit - one verdict, tied to the forcing edge. Extend an existing seam when the work lands inside a boundary whose dependency arrow already points the right way and that already carries the concern; refactor first when landing it as-is would open a cycle, invert a layer, or overload a shared grab-bag (name the exact edge); isolate a new boundary when it is a genuinely new concern with no existing home. Verify each dependency claim against located code, never a name. The verdict is judged against the
Asked: line (Output, below) - the user's own words for what changes and what must go away - not against what the code makes convenient. Before designing anything new, search for it in this order and stop at the first rung that holds: the existing code (the map's patterns in play, the navigation tools), the docs of the libraries already referenced (the documentation tools), the package registry for a maintained package, then the web - and the ## Decisions line for that call names the rung that held.
- Decompose into an ordered, minimal plan. Load
habits-plan-writing first (the Skill tool), then break the work into tasks that each own a clear slice, in dependency order, each naming the files it touches, the stack traps it must handle, the file:symbol anchors you located, and its log_points (the design rules below). A task whose code reaches a capability the project wraps carries in its anchors the app's own seam a task's code must go through; when the seam lacks the member, the interface, its implementation and their test are that task's files. The smallest plan that meets the requirement - nothing speculative added, nothing required left out. A cited spec row, card or spec file, tasks that may build in parallel, or a bug seen only on the customer's side - read references/design-rules.md before writing the tasks.
The design rules - decided here, audited later
Three questions on every seam you draw: is this the right TIME for the abstraction, the right PLACE
for the code, and can it lie to a reader or hold a bad state? The plan answers them before an
implementer inherits the answer.
- YAGNI + rule of three - design the direct solution; the seam goes in at the third occurrence, split on what actually varied.
- High cohesion, low coupling - everything a task owns changes for the same reason; a boundary that splits one axis of change across two seats is the wrong boundary.
- Program to an interface at boundaries ONLY - an external system, something the tests mock, something with a credible second implementation.
- Illegal states unrepresentable where cheap, fail fast everywhere else - and composition by default, since a subtype that cannot stand in for its base is a design defect.
- Command-query separation - a method either mutates or answers, never both.
- Least astonishment - the name is the contract.
- Patterns are refactored TOWARD, never started from - absent a trigger already in the code, the simpler structure wins.
references/design-rules.md carries all seven in full, each with the failure shape it prevents,
plus the SOLID review stance, and the observability spec below - Read it at method step 4, beside the habits-plan-writing load,
before the decomposition is written.
Observability is designed at the seams, never sprinkled by the implementer. Stamp each task
card with log_points - where a line goes, at what level, carrying which identifiers - or
log_points: none - <reason>, since an absent field and a considered none must never look alike.
Which crossings and decision points earn a line, the level ladder, the join keys a message carries,
and the log-once rule are in the reference.
Every judgment call lands on the plan with its precedent. The plan carries a ## Decisions
ledger - one line per call the design made where the requirement left two defensible shapes (a
library, a structure, a pattern, a placement, a name at a seam): the choice - precedent: <file:symbol or named rule>, or no precedent - <reason> said explicitly and still decided; a plan with no such
call writes ## Decisions: none - <reason>, so an absent ledger and a considered none never look
alike. The implementer inherits each answer and leaves its why at the line; the reviewer gates the
built code against the ledger. A choice the project recorded - its instructions, architecture or code-style
docs - is a decision, never a defect to design around: judge the fit against what it
chose, not a convention it does not use. A user preference (alfred-preferences.md) outranks them all:
its row names the id; one a skill or another instruction contradicts is the user's call - ask which wins, the
entry's side marked (Recommended), a seat on user_decisions: - and one no design meets goes to the user (a seat:
NEEDS_CONTEXT), never waived. A
new file's home is a decision too: the folder the repo's best-organized module uses for that kind of
file, never a new common / helpers / utils dump folder. A how-to-build call is never left to the
build or bounced to the user. One call is never the design's: a change to a behaviour the user can see
that the Asked: line does not name (a value now always shown, a default flipped, an exit path
changed) gets its own ask before the gate, its ledger line carrying asked: <the answer>; under
AUTO the behaviour stays as it was, not asked - kept as is (AUTO); inside a designer seat it is a
user_decisions: row, asked: pending. An option description is not an ask. A design ask - or a seat's
user_decisions: row - states only measured facts, each with how it was measured (a run, a test, a located
file:symbol); an unmeasured behaviour is never a premise the user is asked to accept: it becomes a plan
check, a first step that measures it before any task builds on it.
<the behaviour change, one line> - today: <what runs now> (measured: <the run or `file:symbol`>). Keep today's behaviour or change it as designed?
- 'Keep today's behaviour (Recommended)' - the `Asked:` line does not name this change, so the plan works around it
- 'Change it as designed' - the plan builds the change; the ledger line records this answer
Output
An ordered task plan: the fit verdict and its forcing edge first, then one entry per task - what it does, the files, the traps to handle, the located anchors, the log points - in build order, then the ## Decisions ledger (or its explicit none).
Two header lines open the plan file, both required fields and not niceties:
Oriented: - the architecture doc read (or the bounded pass) and the preference and assessment docs read (or none present) from step 1, the awareness doc for a sibling-repo seam, plus the house skill(s) loaded in step 2, or none - <reason>. If you cannot fill it, those steps did not happen - do them now; a plan designed blind ships the traps it never saw.
Asked: "<the user's words, verbatim>" - the request as the user put it, including what must NOT survive (a method to remove, a path to replace). The fit verdict is judged against this line and task-verify-plan's scope pass reads it.
task-verify-plan grades both: a missing Oriented: is a MAJOR finding, a missing Asked: a MINOR one.
Write and hand off
A DISPATCHED designer seat has no Write tool: it returns the whole plan in its report, Oriented: line first, and the orchestrator writes the file from it - the seat's work ends there. In this chat the plan goes to <docs-path>/work/plans/<feature>.md before handing off - a design flow writes it as its handoff, the case the interaction rule's plan-file line names. Read references/write-and-hand-off.md once the plan is settled and follow it - it writes and verifies the file, hands off, and carries a worked plan.
Plan format
The plan file's one shape is the habits-plan-writing skill, loaded at method step 4. The execution mode is the build step's ask, never the plan's. An external claim in the plan - a vendor API's behavior, a package's capability, a rate limit - is verified via the documentation tools or the vendor doc and cited, or marked unverified; never recall stated as fact.
1---2name: task-design3description: "Use to settle how a feature fits the existing code before writing any - 'design this feature', 'plan this change'. Not for one-line edits or a plan audit."4metadata:5 source: https://skillmd.com/skills/envoydev/task-design6---78# Solution Design - how a change fits, then decomposed, in one chat910The design carries the quality: a build handles the traps its plan named and ships the ones it missed. This is the single-chat form of the solution-designer seat - it works out where a feature belongs in the code you already have and breaks it into an ordered plan in this chat. It plans; the build step writes the code. The measurements behind these rules live in `references/evidence.md` - an audit appendix, not a run-time load.1112## Design mode - this chat, a read fan-out, or the designer seat1314In this chat, ask the mode per `references/design-mode.md` - read it before designing; a mode the invocation or a calling flow already picked is inherited, never re-asked. Inside a designer seat: no ask, no dispatch - the dispatch is the answer, run the method below. A seat holds no AskUserQuestion, so each ask below is a report field there: an ambiguous brief returns NEEDS_CONTEXT (step 0), a behaviour change goes on the report's `user_decisions:` line (the Decisions ledger).1516## When to use / not1718- Not for a change with an obvious single home - just make it.19- Not plan *audit* (`task-verify-plan`) or built-code review (`task-verify-code`) - those come after.2021## The method - orient, judge, decompose22230. **Settle the ask first.** Before you orient or design anything, load `habits-clarify` (the Skill tool) and run it: an ambiguous, underspecified or multi-reading ask is settled with the user before the design starts, and its answers are the requirement the plan cites. A clear ask passes straight through. Inside a designer seat, load nothing here: an ambiguous brief returns NEEDS_CONTEXT naming the readings to settle.241. **Orient from the project docs, don't re-derive them.** Consult `<docs-path>/awareness/ARCHITECTURE-AWARENESS.md` SCOPED, never whole: grep it for the modules the task touches plus a listing of `<docs-path>/awareness/references/`, then read the matching section ranges and the area's linked topic file. A `docs.js where` call only lists sections: read the ones it names (`docs.js show`, or the range) and cite that read, never the `where`. Absent that doc, take a bounded pass over the modules involved: a directory listing, then a file outline per file that matters, never a whole-file read. Either way `Oriented:` cites the EVIDENCE - the ranges read, the symbol calls made: the gate checks it against the session, and an orientation with no matching reads is a MAJOR finding. Read the preference docs that exist too (`<docs-path>/preferences/`: `PERSONAL-CODE-PREFERENCES.md`, `ARCHITECTURE-PREFERENCES.md`, `PROJECT-CODE-PREFERENCES.md`) and both assessments (`<docs-path>/quality/`: `CODE-ASSESSMENT.md`, `ARCHITECTURE-ASSESSMENT.md`) scoped to the task's modules - an entry is a lead, and no card adds a case of a weakness one records. A seam with a sibling repo: the related-projects awareness doc, already in context, names its far side.252. **Load the house skill for the stack you're in, for its real trap list.** Your project's convention rules auto-attach it the moment you touch a matching file; load it explicitly if you're designing before touching code. Carry the stack's real traps, not a generic checklist, and follow that skill's own routing to its specialist siblings (the stack -> skill map lives in the project's convention rules and router skills, not restated here).263. **Judge the fit - one verdict, tied to the forcing edge.** Extend an existing seam when the work lands inside a boundary whose dependency arrow already points the right way and that already carries the concern; refactor first when landing it as-is would open a cycle, invert a layer, or overload a shared grab-bag (name the exact edge); isolate a new boundary when it is a genuinely new concern with no existing home. Verify each dependency claim against located code, never a name. The verdict is judged against the `Asked:` line (Output, below) - the user's own words for what changes and what must go away - not against what the code makes convenient. Before designing anything new, search for it in this order and stop at the first rung that holds: the existing code (the map's patterns in play, the navigation tools), the docs of the libraries already referenced (the documentation tools), the package registry for a maintained package, then the web - and the `## Decisions` line for that call names the rung that held.274. **Decompose into an ordered, minimal plan.** Load `habits-plan-writing` first (the Skill tool), then break the work into tasks that each own a clear slice, in dependency order, each naming the files it touches, the stack traps it must handle, the `file:symbol` anchors you located, and its `log_points` (the design rules below). A task whose code reaches a capability the project wraps carries in its anchors the app's own seam a task's code must go through; when the seam lacks the member, the interface, its implementation and their test are that task's files. The smallest plan that meets the requirement - nothing speculative added, nothing required left out. A cited spec row, card or spec file, tasks that may build in parallel, or a bug seen only on the customer's side - read `references/design-rules.md` before writing the tasks.2829## The design rules - decided here, audited later3031Three questions on every seam you draw: is this the right TIME for the abstraction, the right PLACE32for the code, and can it lie to a reader or hold a bad state? The plan answers them before an33implementer inherits the answer.34351. **YAGNI + rule of three** - design the direct solution; the seam goes in at the third occurrence, split on what actually varied.362. **High cohesion, low coupling** - everything a task owns changes for the same reason; a boundary that splits one axis of change across two seats is the wrong boundary.373. **Program to an interface at boundaries ONLY** - an external system, something the tests mock, something with a credible second implementation.384. **Illegal states unrepresentable where cheap, fail fast everywhere else** - and composition by default, since a subtype that cannot stand in for its base is a design defect.395. **Command-query separation** - a method either mutates or answers, never both.406. **Least astonishment** - the name is the contract.417. **Patterns are refactored TOWARD, never started from** - absent a trigger already in the code, the simpler structure wins.4243`references/design-rules.md` carries all seven in full, each with the failure shape it prevents,44plus the SOLID review stance, and the observability spec below - Read it at method step 4, beside the `habits-plan-writing` load,45before the decomposition is written.4647**Observability is designed at the seams, never sprinkled by the implementer.** Stamp each task48card with `log_points` - where a line goes, at what level, carrying which identifiers - or49`log_points: none - <reason>`, since an absent field and a considered none must never look alike.50Which crossings and decision points earn a line, the level ladder, the join keys a message carries,51and the log-once rule are in the reference.5253**Every judgment call lands on the plan with its precedent.** The plan carries a `## Decisions`54ledger - one line per call the design made where the requirement left two defensible shapes (a55library, a structure, a pattern, a placement, a name at a seam): `the choice - precedent: <file:symbol56or named rule>`, or `no precedent - <reason>` said explicitly and still decided; a plan with no such57call writes `## Decisions: none - <reason>`, so an absent ledger and a considered none never look58alike. The implementer inherits each answer and leaves its why at the line; the reviewer gates the59built code against the ledger. A choice the project recorded - its instructions, architecture or code-style60docs - is a decision, never a defect to design around: judge the fit against what it61chose, not a convention it does not use. A user preference (`alfred-preferences.md`) outranks them all:62its row names the id; one a skill or another instruction contradicts is the user's call - ask which wins, the63entry's side marked (Recommended), a seat on `user_decisions:` - and one no design meets goes to the user (a seat:64NEEDS_CONTEXT), never waived. A65new file's home is a decision too: the folder the repo's best-organized module uses for that kind of66file, never a new `common` / `helpers` / `utils` dump folder. A how-to-build call is never left to the67build or bounced to the user. One call is never the design's: a change to a behaviour the user can see68that the `Asked:` line does not name (a value now always shown, a default flipped, an exit path69changed) gets its own ask before the gate, its ledger line carrying `asked: <the answer>`; under70AUTO the behaviour stays as it was, `not asked - kept as is (AUTO)`; inside a designer seat it is a71`user_decisions:` row, `asked: pending`. An option description is not an ask. A design ask - or a seat's72`user_decisions:` row - states only measured facts, each with how it was measured (a run, a test, a located73`file:symbol`); an unmeasured behaviour is never a premise the user is asked to accept: it becomes a plan74check, a first step that measures it before any task builds on it.7576```ask77<the behaviour change, one line> - today: <what runs now> (measured: <the run or `file:symbol`>). Keep today's behaviour or change it as designed?78- 'Keep today's behaviour (Recommended)' - the `Asked:` line does not name this change, so the plan works around it79- 'Change it as designed' - the plan builds the change; the ledger line records this answer80```8182## Output8384An ordered task plan: the fit verdict and its forcing edge first, then one entry per task - what it does, the files, the traps to handle, the located anchors, the log points - in build order, then the `## Decisions` ledger (or its explicit none).8586Two header lines open the plan file, both required fields and not niceties:8788- `Oriented:` - the architecture doc read (or the bounded pass) and the preference and assessment docs read (or `none present`) from step 1, the awareness doc for a sibling-repo seam, plus the house skill(s) loaded in step 2, or `none - <reason>`. If you cannot fill it, those steps did not happen - do them now; a plan designed blind ships the traps it never saw.89- `Asked: "<the user's words, verbatim>"` - the request as the user put it, including what must NOT survive (a method to remove, a path to replace). The fit verdict is judged against this line and `task-verify-plan`'s scope pass reads it.9091`task-verify-plan` grades both: a missing `Oriented:` is a MAJOR finding, a missing `Asked:` a MINOR one.9293## Write and hand off9495A DISPATCHED designer seat has no Write tool: it returns the whole plan in its report, `Oriented:` line first, and the orchestrator writes the file from it - the seat's work ends there. In this chat the plan goes to `<docs-path>/work/plans/<feature>.md` before handing off - a design flow writes it as its handoff, the case the interaction rule's plan-file line names. Read `references/write-and-hand-off.md` once the plan is settled and follow it - it writes and verifies the file, hands off, and carries a worked plan.9697## Plan format9899The plan file's one shape is the `habits-plan-writing` skill, loaded at method step 4. The execution mode is the build step's ask, never the plan's. An external claim in the plan - a vendor API's behavior, a package's capability, a rate limit - is verified via the documentation tools or the vendor doc and cited, or marked `unverified`; never recall stated as fact.