RepoSkillOpt — To-Be Design & Implementation Orchestration (Canonical Skill)
Purpose
This skill consumes the as-is artifacts (Architecture View + Change-Impact Analysis) and a
stated goal, and produces (a) a reviewable target-state design — ADRs + a concise Design
Doc grounded in the as-is evidence — and (b) an implementation orchestration plan: a
machine-readable Task Ledger decomposed into small, independent, individually acceptance-tested
sub-tasks with declared dependencies and a topological order. The plan is an artifact, not an
executor — any orchestrator can drive it; this skill never executes the implementation.
Vendor-neutral: no dependency on any particular coding-agent runtime.
Trigger Conditions
Activate when the user asks to design a target state / to-be, plan the work / decompose into
tasks, or produce an implementation plan for goal X — or recognizable equivalents. Do not
activate for unrelated requests, and do not execute the resulting plan.
Prerequisite
The as-is artifacts (Architecture View, Change-Impact Analysis) and a stated goal. If the as-is is
missing, point the user to the as-is architecture skill first; do not design against an ungrounded
picture of the current system.
Operating Principles
- Ground the design in the as-is. Every design claim is traceable to as-is evidence (
via the cited as-is artifacts). Mark inference as , unknowns as .
- Decide explicitly. Contested choices become ADRs that weigh ≥2 options — no silent defaults.
- Plan, don't execute. The Task Ledger is a portable artifact; this skill writes it and stops.
- Independent, acceptance-tested tasks. Each sub-task is small enough to be executed and
reviewer-verified on its own, with declared dependencies; if a task isn't independently
acceptance-testable, split it.
- Repository facts stay repository-scoped. Only candidate-for-generic patterns enter convergence.
Workflow
(a) Read the as-is artifacts + the goal. Identify constraints and the affected blast-radius.
(b)
ADRs (
.reposkillopt/decisions/ADR-NNN-<slug>.md
, per
): one decision
each — Context,
Options considered (≥2, pros/cons), Decision, Consequences. A goal that conflicts
with an as-is constraint is recorded as an ADR trade-off, not papered over.
(c)
Design Doc (
.reposkillopt/design/design-doc.md
, per
): Goal,
Target-state overview,
How it maps onto the as-is (each change tied to the current
component/flow it touches, cited), Risks & trade-offs (link the ADRs), Out of scope.
(d)
Task Ledger (
.reposkillopt/plan/task-ledger.md
, per
): the work
as a table —
id | goal | acceptance | depends_on
— each task independent + individually
acceptance-tested, dependencies declared, the dependency graph
acyclic, and the front-matter
listing every id with each dependency before its dependent.
(e)
Deterministic gate. The artifacts MUST pass the deterministic checks (
,
): ≥2 options per ADR; every task has a goal + acceptance; deps exist; graph
acyclic; topological order valid.
Output Discipline
Same R10 labels and citation forms as the as-is skill; design claims cite the as-is artifacts they
rest on. Trivial recitations need no label.
Human Feedback Loop
Corrections to a decision or to the task decomposition are recorded as
Feedback Items
(
templates/human-feedback.md
) under
and applied to the artifact in place.
Skill Convergence Loop
Recurrent
candidate-for-generic feedback (≥3 related items) becomes a
Skill Edit Proposal
(
templates/skill-edit-proposal.md
), accepted
only after the validation gate
(
rubric/validation-gate.md
): regenerate artifacts for a disjoint held-out set with
no
per-dimension rubric regression (see
rubric/tobe-orchestration-rubric.md
) and deterministic
checks still passing. Nothing is silently promoted; acceptance bumps the version + CHANGELOG and is
mirrored into the four adapters.