Creates an evidence-backed development plan or design document for a non-trivial ysonet change and saves the draft under dev-kitchen/ideas/ for review before implementation. Use when the user asks to plan, propose, design, research a proposed change, or draft an approach for a refactor, architecture or UI change, new gadget, plugin, serializer, build change, dependency change, or other work that should be settled before code is written. Not for immediate implementation, diagnosis-only requests, or tiny mechanical edits.
Creates an evidence-backed development plan or design document for a non-trivial ysonet change and saves the draft under dev-kitchen/ideas/ for review before implementation. Use when the user asks to plan, propose, design, research a proposed change, or draft an approach for a refactor, architecture or UI change, new gadget, plugin, serializer, build change, dependency change, or other work that should be settled before code is written. Not for immediate implementation, diagnosis-only requests, or tiny mechanical edits.
Create a ysonet development plan
Produce a decision-ready plan, not product code. Keep the draft in the private,
git-ignored dev-kitchen/ workflow:
dev-kitchen/ideas/: proposal under research or review;
dev-kitchen/to-be-implemented/: user-approved, settled plan; and
dev-kitchen/already-implemented/: optional record after delivery.
Do not implement the change while using this skill.
Quality bar
Plan for the durable solution, not the quickest one that meets the request.
Recommend the design that lasts longer and makes the app easier to extend,
even when it costs more work. Say plainly when that is the trade.
Do not plan a workaround, a special case, or a partial wiring as the main
design unless a hard constraint blocks the proper fix. Then record the
constraint, the proper fix, and a dev-kitchen/todo/ note.
Plan the complete change: implementation, every applicable serializer and
formatter, tests, docs, help, completion, interactive UI, and architecture
updates. A plan that stops at the happy path is not decision-ready.
Reuse and improve existing shared patterns and helpers instead of proposing a
parallel one-off. Prefer the general mechanism when the cost is small; do not
invent abstraction nobody needs.
If the quality option needs more scope or a maintainer decision, put that in
the plan and ask. Do not quietly shrink the outcome to fit the effort.
Workflow
1. Load repository guidance
Read CLAUDE.md, .claude/memory/memory.md and every indexed memory file,
docs/ARCHITECTURE.md, and CONTRIBUTING.md. Then read the complete files in
scope. Use the architecture document as a map and verify it against current
source.
Inspect git status --short before planning so existing user work is not
mistaken for the proposed change.
2. Define the planning question
State:
the requested outcome;
explicit non-goals;
the expert perspective used for the plan;
decisions the plan must settle; and
facts that are currently assumptions or unknown.
Choose the perspective that fits the work, such as .NET maintainer, software
architect, console UX designer, build engineer, or security researcher. Keep
the plan factual rather than role-playing.
3. Gather evidence before designing
Verify every load-bearing claim with the current repository. Check as relevant:
exact files, symbols, call paths, and line or file counts;
namespaces and imports;
old-style csproj <Compile Include=...> entries for added or moved source;
reflection, Activator.CreateInstance, assembly-qualified-name strings, and
name-based filters;
CLI, interactive, help, completion, and documentation surfaces;
existing gadget, plugin, serializer, or helper overlap;
tests that already protect the behavior and gaps the change would create;
target framework, package versions, and dependency freshness; and
dirty working-tree changes in the same area.
For broad research, divide only independent, read-only scopes among subagents
when delegation is allowed by the current instructions. Give each a bounded
question and verify its findings in the primary thread.
Never design from a reported count, name, or relationship without checking it.
When documentation and source differ, record the drift and treat source as
authoritative.
4. Resolve material ambiguity in the plan file
One plan is one file. This is the plan-file exception in CLAUDE.md under
"Surfacing open items and next steps": every question about this change lives
in the plan's Open questions section until it is answered, then it is folded
into the plan. Never write a second markdown file for the same plan's
questions.
That section is the LAST section of the plan, so the maintainer can scroll to
the end of the file and see everything that needs an answer in one place.
If a question comes up before the draft exists, create the draft now at the
path in step 8 with what is settled so far, and put the question at the bottom
of it. Writing the rest of the plan continues after the answers arrive.
Answer repository-checkable questions yourself. Ask the user only when a choice
would materially change the outcome, scope, compatibility, risk, or public
behavior. For small, reversible details, make and record a reasonable
assumption instead of asking.
For each question that needs the user:
Write it in the Open questions section at the bottom of the plan,
numbered, with the options, concise trade-offs, one recommendation, and what
the answer changes in the plan.
Ask the user the same questions in chat, in one batch, pointing at the plan
path. Do not ask them one at a time across many turns.
When the user answers, edit the plan: apply each answer to the affected
sections, then move the question to Answered questions with the chosen
option, the answer, and the date. Keep the record; do not delete it.
Only then finish the remaining sections, so the plan is complete and ready
to implement in the same pass.
Do not move a plan to to-be-implemented/ while Open questions still has an
unanswered item.
5. Apply project constraints
Record the constraints that shape the design:
all solution projects stay on .NET Framework 4.7.2 unless the user approves a
separate target change;
old-style csproj source registration is manual;
reflection and string-based type names can make moves behavior-sensitive;
dependencies and GitHub Actions follow the one-month freshness and pinning
policies;
vulnerable libraries used inside gadget demonstrations are intentionally
old;
VERSION changes, commits, and pushes require the approvals in CLAUDE.md;
public files cannot contain local paths or other machine-specific artifacts;
and
docs, comments, and help use short plain ASCII text.
Add area-specific constraints from the source rather than copying this list
blindly.
6. Choose one coherent design
Give one recommendation with:
the inclusion rule: what belongs in the change and what does not;
the evidence supporting it;
the strongest alternative and why it loses;
compatibility and migration consequences;
an escape hatch if a key assumption proves false; and
a rollback that preserves user data and existing behavior.
Prefer the smallest complete, maintainable change. Do not propose a temporary
workaround as the main design unless a hard constraint makes it necessary.
7. Plan implementation and coverage
Write file-by-file steps with enough detail that an implementer can work without
re-discovering the design. Include:
source, project, config, and generated-artifact handling;
public CLI, interactive, help, completion, and docs surfaces;
behavior and error cases;
regression tests for every new or changed function and contract;
safe test fixtures and cleanup;
exact verification commands in focused-first, full-last order; and
risk checkpoints that would require returning to the user.
Do not rely only on a broad smoke matrix. Name focused assertions for the
behavior the change introduces. For gadget/plugin work, plan to run only those
module-specific assertions and the safe runtime-effect trigger first, repeat
them until green, and run repository-wide tests only afterward.
For a new or changed gadget, read references/making-a-gadget.md. For a new or
changed plugin, read references/making-a-plugin.md. Check uniqueness before
planning either. Resolve both references/ paths relative to this skill's
directory.
Every .NET Framework gadget plan must explicitly name at least one
evidence-backed working framework version and the intended WithVersions
declaration. If the current/latest candidate does not fire, name the highest
verified older working version and the latest tested non-working version. If no
working version is known yet, write Known working version: not yet verified
plus the exact compatibility experiment under Open questions; do not move the
plan to to-be-implemented/ until that experiment establishes one. Use a single
runtime token when only one target version is proven and a range only when evidence
supports the whole contiguous span. State whether each version describes the
framework the target process runs on or the target application's
TargetFrameworkAttribute; it never describes ysonet's build.
8. Write the draft
Save the plan to dev-kitchen/ideas/<kebab-case-name>.md, one file for the
whole plan. Use the template below as a starting point. Keep verified facts
separate from assumptions and open decisions. Use repository-relative paths and
plain ASCII.
If step 4 already created this file, keep editing it. Do not start a second
file for the same change, and do not split questions, answers, or decisions
out of it.
Do not depend on example plans in dev-kitchen/; that directory is private and
may not contain the same files on another checkout.
9. Hand off deliberately
Review the draft for internal consistency and report its path. Iterate in
ideas/ until the user says the design is settled. Move it to
to-be-implemented/ only when the user approves it as ready, and only when the
Open questions section at the bottom says "None".
Questions, decisions, and limitations that belong to this change stay in the
plan file. Write a dev-kitchen/todo/ note (and update its README.md index)
only for an item this plan will NOT carry: work deferred out of scope, or a
decision the maintainer must make about something else. A todo note must never
duplicate an item the plan already tracks.
Do not commit, bump VERSION, push, or start implementation.
Test and verification rules
Plan gadget/plugin verification in two gates. First compile without starting
the post-build runner:
Then name and run only the changed module's focused generation,
deserialization, formatter/variant/mode/option/minify/error, and safe
runtime-effect checks. Plan to repeat that narrow set until the module triggers
as intended. Put changed-surface smokes and any required Release build in this
focused gate.
Only after that gate passes, plan the normal Debug build and then the FULL tier
LAST for any gadget, plugin, serializer, formatter, minifier, or cross-cutting
payload change:
msbuild ysonet.sln -p:Configuration=Debug -v:minimal -nologo
cd ysonet/bin/Debug
ysonet.Tests.exe --full
The standalone runner must use its output directory as the working directory so
bundled assemblies resolve. Use a final Debug build with
YSONET_FULL_TESTS=1 when that is not the chosen route. If the final regression
finds an issue, plan to fix it, rerun the affected focused checks, and rerun
FULL so the final tested state ends with a green FULL suite. Do not use a
Release build as a substitute for the Debug tests.
Name focused smoke commands for changed reflection-driven surfaces, such as
--list gadgets, --list plugins, module options, category filtering, and a
representative payload, and place them before the final FULL gate.
Plan template
# Plan: <shorttitle>
Status: proposal for review. Not implemented.
Role: <relevantexpertperspective>.
## 1. Goal and non-goals
State the outcome and explicit boundaries.
## 2. Verified current state
List evidence from current code, tests, docs, and project files.
For a .NET Framework gadget, include these explicit fields:
- Known working target version: <versionandevidence>.
- Latest tested non-working target version: <versionandevidence, ornone>.
- Version describes: <targetprocessruntimeorTargetFrameworkAttribute>.
- Planned WithVersions: <singletokenorevidence-backedrange>.
## 3. Constraints
List only constraints that shape this design.
## 4. Design decision
Give the recommendation, inclusion rule, strongest rejected alternative, and
escape hatch.
## 5. Target shape
Show the resulting files, ownership, flow, or public behavior.
## 6. Implementation sequence
Give ordered, file-specific changes and checkpoints.
## 7. Tests
Name focused cases, matrix changes, fixtures, cleanup, and expected failures.
For a .NET Framework gadget, include the compatibility run that earns the
planned `WithVersions` token or range.
Name architecture, catalog, help, completion, and other updates.
List exact focused checks and trigger first, then smoke and optional Release
commands, then the normal Debug and final FULL regression commands.
State failure modes, mitigations, and a recoverable rollback.
List the settled decisions and any follow-up that this plan will NOT carry,
with its note path. Questions for the user go in the two
sections below, not here.
Last section of the file on purpose: the maintainer scrolls to the end and sees
everything that needs an answer. Numbered questions, each with the options,
short trade-offs, one recommendation, and what the answer changes in this plan.
Write "None" once all are answered; the plan is not ready to implement until
then.
Each answered question with the user's choice and the date, kept as a record.
Final checks
Repository guidance, memory, architecture, and in-scope source were read.
Every load-bearing claim was verified against current files.
Existing user changes and overlapping features were identified.
Questions for the user sit in Open questions at the BOTTOM of the plan,
were asked in one batch, and no separate question file was created.
Every answer was folded into the affected sections and recorded under
Answered questions.
Material choices were settled; smaller assumptions are explicit.
One recommendation and the rejected alternative are justified.
Source, csproj, public surfaces, docs, tests, and rollback are covered.
Gadget/plugin verification runs focused tests and trigger evidence first.
Every .NET Framework gadget plan names a verified working version and its
intended WithVersions declaration; a latest-version failure names the
highest verified working version and the latest tested non-working one.
Smokes and optional Release checks precede the final regression gate.
Verification uses Debug tests and ends with FULL when the scope requires it.
Gadget or plugin plans follow the matching bundled reference.
The whole plan is one file under dev-kitchen/ideas/, and a
dev-kitchen/todo/ note exists only for work this plan will not carry.
No implementation, commit, version bump, or push was performed.
