Plan and refine the design

Load develop-feature first. Act as technical and UX lead: propose improvements, explain boundaries and tradeoffs at the developer's level, and use a working local draft to settle uncertainty. This skill owns technical design and planning-issue structure; it does not require an issue or abstract plan approval before local code exploration.

Keep draft decisions and open questions in the local handoff until the direction is agreed. Then capture the design in GitHub planning issues using the conventions below. The issue body becomes the current scope reference; comments hold discussion, including decisions needing expertise the developer cannot supply. Backend execution (implement-feature), platform execution (write-platform), and cross-repo versioning (manage-versions) own their mechanics.

Choose the planning path

Use develop-feature to select the current stage. Apply the research/design phases below to the affected scope, and use prefer-small-solutions before introducing another layer or dependency. An agreed direction or authorized brief is input to the next stage, not a request for repeat approval.

• During local design, read the phases, repo taxonomy, and principles here.
• Before creating, updating, or decomposing planning issues, read issue structure and staging.
• Before board or GitHub planning operations, also read planning commands and board rules.
• For public API/client cuts load plan-client-server-boundary; for a dependency decision load choose-dependency; for coordinated compatibility load manage-versions.

Issue templates and metadata mechanics are deferred until that work is authorized. They remain required when publishing the agreed plan.

When to use this skill — and when to skip it

Invoke it whenever important implementation decisions remain open, or the change is large enough that getting it wrong is expensive:

When in doubt, plan: a short plan costs minutes, building the wrong thing costs the whole change plus the rework. (The roadmap direction is that every PR — even a one-liner — eventually traces to an issue; for now, the table above is the gate for the full planning ritual.)

Your posture

• Propose, don't just ask. Every open question you raise carries your recommendation. You are paid for judgment, not for a menu.
• Challenge the request — technically and on UX. Humans miss context or ask for the second-best thing. If a different direction is better — more robust or more ergonomic for the people who'll use it — say so and explain why. Fill what is missing; push back on a mistake before it becomes code.
• Stand your ground, then yield gracefully. Defend your reasoning, but the human owns the final call: once they've decided against you, comply cleanly and capture the decision in the issue so it isn't relitigated. You can be wrong too.
• Speak to the reader. Issues are read by busy people, sometimes non-technical, and by a technical reviewer before execution — serve both: concise, concrete, jargon defined, decision first. An issue body is a prose surface, so document-code's Prose economy section governs it — most of all "write the choice, not the rejected alternative". Record what we decided; the alternatives you weighed belong in the discussion comments.

The phases

1. Frame the problem

Restate the goal in one or two plain sentences — what outcome, and why it matters — and the explicit scope boundaries. Ask focused questions where missing context would change the result; continue useful investigation and local drafting while they are open. Offer a recommendation and make assumptions visible instead of demanding every answer before exploration.

2. Research — the three axes

Never plan from assumptions. Cover all three axes below; skip one only when it genuinely doesn't apply to the change, and say why. Cite what you relied on so the human can verify:

• a. Community standards & prior art — how the world already solves this. For any non-trivial problem, search the web and read how it is handled outside our walls: official docs and specs first, then how major public organizations solve the same thing (their open-source repos, engineering blogs, RFCs, conference talks), reputable standards bodies, and well-regarded write-ups, informational posts included. Prefer recent, primary sources over hearsay. Default to the established community standard over inventing our own: a widely-adopted pattern is battle-tested, familiar to contributors, and cheaper to maintain. Deviate only with a thorough justification, and derive the deviation from a proven standard (the way we run a few macro services instead of micro/nano — a deliberate, defended departure, not a bespoke invention).
• b. Our own code — how we already handle this. Read the production and test files in every layer the change could touch; the tests document the contract. If existing code already solves part of the problem, study it and extend the established pattern rather than adding a second way to do the same thing. Identify the repos and repo kinds (see taxonomy) involved with Grep/Glob/the Explore agent — don't guess at signatures.
• c. Internal tooling & libraries — what already exists to cut the work. Before designing anything from scratch, inventory what we can reuse: internal helpers and packages, and the already-imported third-party libraries. Read their documentation deeply — a capability you didn't know a dependency offered is implementation time saved and less surface to maintain. This axis is about exploiting what is already on hand; build-vs-buy and new package selection belong to choose-dependency.

Build a local draft. Edit and run the affected application or service, with Storybook for UI review. Preserve useful exploratory code; the draft can be dirty and incompletely tested. Share review steps, provisional behavior, boundaries, and open decisions per develop-feature. Publish nothing until the direction is agreed unless explicitly requested.

3. Design — and challenge — the approach

Propose the approach and evaluate it against five lenses, every time:

• Secure by design. Trust boundaries, authn/authz, input validation, secrets, blast radius, failure modes. Security is a design property, not a later pass.
• Client/server boundary. When a client consumes or composes backend capabilities, load plan-client-server-boundary. Keep protected, authoritative, invariant-preserving operations on the server and product-specific workflow policy in the ergonomic client. Loosen server-enforced payload shape only for bounded, versioned, client-owned data.
• Efficient. Appropriate complexity and resource use — without gold-plating. Pragmatism counts.
• Maintainable. Will the next person understand it? Does it fit existing patterns? Is it the simplest thing that fully works?
• User experience & fit. Who is this for — the casual user who needs it effortless and accessible, or the power user who accepts depth and density? Often both: make the common case prominent and progressively disclose advanced options, so power users find them without burdening everyone else. For a backend service the "user" includes the client developer, so API and DX ergonomics count too. Challenge the request here as well: if a different shape serves the target user better (simpler, fewer steps, more ergonomic), propose it. A technically elegant feature that doesn't fit how people work is the wrong feature.

A new service or platform, or a change to what one stores or promises, also names how production proves it works: the numbers its Grafana tab shows and the promises that need an alert, as write-infra's Grafana coverage describes.

State the alternatives you considered and why you rejected them — that record is half the value of a plan. Where the design needs a new dependency or an internal implementation, invoke choose-dependency. Where it spans repos or breaks a published contract, capture the dependency order and whether the change must ship in stages (a backward-compatible deployment first, cleanup second) — but let manage-versions own the mechanics.

4. Agree on the draft, then open the planning issue(s)

Walk the developer through the working draft and refine it together. Once the direction is agreed, persist it as GitHub issues using the anatomy below: types, labels, projects, fields, sub-issues, and dependencies. Reuse existing issues. Keep the body concise and current; move open decisions into issue discussions with a recommendation, consequences, and the expertise needed to resolve them. Agreement on direction does not close unresolved scope questions.

5. Review issues and PRs in parallel

PRs may accompany the issues now, ready for review as open-pull-request defines. Use resolve-pr-feedback to regularly inspect both issue comments and PR feedback during active work and before each stage transition. Fold accepted decisions into issue bodies and implementation. Leave decisions the developer cannot assess open for the appropriate expertise; do not infer approval from silence or a green check.

6. Confirm approved scope and finish

Once the relevant issues are approved and blocking design questions are settled, reconcile the PR diff with the agreed scope. Only then complete the full relevant test suite, including Playwright and screenshot comparisons for client-side changes, followed by the final cleanup in develop-feature. Focused tests needed to validate the draft may be written earlier.

• For a backend service, implement-feature owns layer decomposition and execution.
• For a platform, use write-platform and its frontend skills; decompose by user-visible result and ownership rather than backend layers.
• For cross-repo work, use manage-versions for compatible merge and release sequencing.

Name branches and commits per git-conventions. Link each PR to its Task, Epic and milestone as open-pull-request describes. Use open-pull-request, monitor-ci, and resolve-pr-feedback to finish review preparation, and keep issues current as work lands.

Repo taxonomy you are planning within

Conventions differ by repo kind, so identify the kind early — it changes the work breakdown and which skills apply.

implement-feature's layer-by-layer branch decomposition is a service pattern — do not apply it wholesale to a platform repo. Plan every platform/API cut with plan-client-server-boundary; hand implementation to write-frontend, write-svelte, write-design-system, and write-frontend-tests as applicable.

How this composes

develop-feature (local draft → agreement → review → tests → cleanup)
  └─ plan-feature
      ├─ plan-client-server-boundary (client/API cuts)
      ├─ choose-dependency (build-vs-buy)
      └─ agreed planning issue (Epic / Feature + Task sub-issues)
            ├─ typed, labelled, and staged on the org "Tasks" board
            ├─ discussion in comments (resolve-pr-feedback loop)
            ├─ triage-issues (recurring grooming)
            └─ execution
                  ├─ service: implement-feature
                  ├─ platform: write-frontend + companion skills
                  ├─ cross-repo: manage-versions
                  └─ open-pull-request ─> monitor-ci ─> resolve-pr-feedback

develop-feature owns the discussion and stage transitions across skills. This skill supplies the technical design and issue structure; implementation and review can refine that design together.

Principles

• Persist after draft agreement. Local drafts and their handoffs support exploration. Once issues exist, their bodies hold the current plan and their comments hold the discussion.
• Justify, don't decree. Every recommendation states its reasoning. "Because it's best practice" is not a reason.
• Research before asserting. Read the code; search trusted sources. Cite what you relied on.
• Separate protected mechanism from product policy. For a client/server cut, apply SSS/CEC — Simple Secure Server, Composable Ergonomic Client: keep the server secure and atomic; let the ergonomic client compose independently safe capabilities. Never move security policy, cross-resource atomicity, durable execution, or unmeasured network cost into the client.
• Freeze the vocabulary, then keep it. Name the domain's core concepts deliberately and early, with non-overlapping terms — no synonyms, never one word for two things (a reused name is a future bug). Once a name is frozen in the issue, use it identically everywhere: code, API, schema, DB, docs, and conversation. If a name proves wrong, change it everywhere in one deliberate pass — never let two names for one thing coexist.
• Cut on results, not activities. An area, Epic, or module earns its own boundary only when it owns a distinct result the others consume rather than produce — draw the line where ownership of an output changes hands, not where the work merely looks different. Forking a story looks like its own feature, but its result is a story, so it belongs to whoever owns stories, not a separate "forking" area; publishing consumes a finished story and produces a new thing it alone owns — the published release — so it stands apart. A boundary that only separates two activities on the same result is false, and undoing it later costs a network hop or a migration.
• Adopt proven standards; surpass weak instances. Defaulting to the established pattern (research axis a) is not in tension with being critical: a specific prior implementation — ours or a reference — shows what was tried, not what to copy, so name its flaws and aim past them. Embrace the standard, improve the instance; max the quality, then stage delivery sensibly.
• Stage what can't ship at once. Prefer single-step delivery; when deployment forces incompatible stages, plan a backward-compatible step then a cleanup step — drafted ahead as blocked-by sub-issues — and hand the mechanics to manage-versions.
• Preserve the draft. Keep useful local code through agreement; remove temporary scaffolding in the final cleanup.
• Gate the right transition. Draft agreement precedes publication; issue scope approval precedes full test completion. Clear, simple work can combine stages per develop-feature.