[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7B3GSR57TB51BX02CS3TYXD":3,"skill-same:01M7B3GSR57TB51BX02CS3TYXD":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7B3GSR57TB51BX02CS3TYXD","designing-changes",null,"Use when asked to build, add or change behavior and the approach has not been agreed yet, when a request is open-ended or ambiguous about scope, or when an idea needs shaping into a design before any code is written.","vadimvitvickiy\u002Fvv-agent-kit","vadimvitvickiy","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F5019512?v=4","01M7B3ABRYF7KHBCDW6GB2XH0C","Vadim Vitvitskii","01M7B3ABSZYG9MXP1CC7BQYM25",0,"MIT","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fdesigning-changes\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: designing-changes\ndescription: Use when asked to build, add or change behavior and the approach has not been agreed yet, when a request is open-ended or ambiguous about scope, or when an idea needs shaping into a design before any code is written.\n---\n\n# Designing changes\n\n**Agree on what to build before building it.** The expensive failure is a correct implementation of\nthe wrong thing, found when the human reads a finished diff.\n\n## Classify the request out loud\n\nSay which kind it is before the first question, so the human can correct it:\n\n| Kind | What it is | What it produces |\n|-|-|-|\n| Spike | A feasibility question — \"can we\", \"is it possible\" | An answer. Anything built is labelled throwaway |\n| Bounded | A scoped change to a flow that already exists in this repo | A short design in chat |\n| Architectural | A new project or subsystem, or a change to how components fit or to an interface others depend on | A written design, then a plan |\n\n- **Bounded is a property of the repo, not your familiarity.** The flow must exist here, readable. A\n  new project is never bounded.\n- Unsure between two kinds: take the heavier. Complexity found mid-task upgrades the kind — stop and\n  say so. Nothing downgrades.\n\n## The artifact scales, the approval does not\n\n- A bounded design may be three sentences. It still ends with the human saying yes, and nothing is\n  implemented until then. Presenting a design and starting on it in one message skips the gate.\n- \"Too simple to need approval\" is where an unexamined assumption costs most — nobody looks twice.\n- **Exception:** a request that already names what to change and where — a function, a behavior, a\n  file — *is* the approved design. Asking to approve it is ceremony.\n\n## Understand before asking\n\n- **Read before you ask** — files, docs, recent commits. Do not spend the human's attention on what\n  the code answers.\n- **Launch a survey as you start reading:** `vvkit:architecture-surveyor` in the background, with a\n  file path for its report. It looks sideways — sibling features, type owners, how an abstraction was\n  last extended. Read it before proposing. Skip only for a one-sentence change.\n- **Check the scope.** Several independent subsystems: name the pieces and their order, design the\n  first.\n- **One question per message**, multiple choice where possible. Five questions get the easy ones\n  answered.\n- **Ask about purpose, constraints and what done looks like** — not details the design settles.\n- **Write your understanding back**: outcome, constraints, success — what the human said kept apart\n  from what you assumed. Invite correction. If the request already states it all, reflect it back.\n\n## Say the premises out loud\n\n- A premise is what was already true and nobody said. Nothing checks it, so rounds of careful design\n  on a wrong one deliver the wrong thing more convincingly each time.\n- Ask **what would have to be true for this to be the right approach?** — who needs it, what the\n  problem costs today, what it is assumed to be free of. Write the answers in the note.\n- Measure a premise that is cheap to measure. Compensation code for an unmeasured problem is the\n  typical casualty.\n- **Premises stay live after approval.** Re-read them when fixes keep landing on new variants of one\n  problem, or when work goes unusually smoothly.\n\n## Shape the design\n\n- **Data shape first.** Get the types and their states right before the logic; make illegal states\n  unrepresentable rather than checked for.\n- **Parse at the boundary, trust inside.** Validate outside data once, where it enters; keep business\n  logic in pure functions behind that boundary.\n- **Redesign, do not bolt on.** Ask what you would have built had the requirement been there from the\n  start; deliver that in pieces. A requirement bolted onto the old shape leaves both shapes behind.\n- **Subtract before you add.** Look for complexity the change lets you remove first.\n- **Operations that can be retried or interrupted are idempotent** — run twice, or after a crash\n  halfway, they end in the same state.\n- **Shared mutable state gets one writer**, enforced by the structure. If two parts do not need the\n  same mutable thing, give each its own.\n- **Extend, never disguise data.** A function that takes another type is asking for a sibling that\n  takes yours. Hand-building another layer's type from data that never came from there invents fields\n  everything downstream trusts.\n- In an existing codebase, follow its patterns. Improve what the change touches when it gets in the\n  way; propose nothing that does not serve the goal.\n\n## Offer approaches, then present in sections\n\n- Two or three approaches with trade-offs, recommended one first, with why. One design turns review\n  into approve-or-reject.\n- Strip every feature nobody asked for. A design is easier to extend than to cut back.\n- Present in sections sized to difficulty, confirming each. A wall of design gets approved in one skim.\n- Mark each choice a **decision** (weighed against a named alternative) or a **default** (something had\n  to be picked). An unmarked default soon looks like a property of the problem.\n- Cover boundaries, data flow, failure behavior and testing. Each unit: what it does, how it is used,\n  what it depends on. A unit you cannot understand without its internals has its boundary misplaced.\n\n## Write it down when it is architectural\n\n- Save it where the project keeps designs. None named: `.agents\u002Fplans\u002F`, only if\n  `git check-ignore -q .agents\u002Fplans` succeeds; otherwise ask.\n- Reread for placeholders or \"TBD\", contradicting sections, a requirement readable two ways (pick one,\n  say which), and scope too large for one plan.\n- Ask the human to review the file. The plan follows — `vvkit:planning-changes`.\n- **Each approval covers the stage shown, nothing after it.** Agreement in chat permits writing the\n  design; an approved design permits the plan; an approved plan, with how it runs, permits code.\n  Resume at the earliest unapproved stage. Reading code is allowed at any stage.\n\n## Before implementing\n\n- [ ] The kind was stated, and the human could correct it\n- [ ] Your understanding was written back, assumptions marked, corrected where wrong\n- [ ] The human said yes to the design, after seeing it\n- [ ] Every open question that changes the design has an answer\n- [ ] Nothing in the design goes beyond what was asked\n- [ ] For architectural work, the design is written, reviewed, and a plan approved\n","# Designing changes\n\n**Agree on what to build before building it.** The expensive failure is a correct implementation of\nthe wrong thing, found when the human reads a finished diff.\n\n## Classify the request out loud\n\nSay which kind it is before the first question, so the human can correct it:\n\n| Kind | What it is | What it produces |\n|-|-|-|\n| Spike | A feasibility question — \"can we\", \"is it possible\" | An answer. Anything built is labelled throwaway |\n| Bounded | A scoped change to a flow that already exists in this repo | A short design in chat |\n| Architectural | A new project or subsystem, or a change to how components fit or to an interface others depend on | A written design, then a plan |\n\n- **Bounded is a property of the repo, not your familiarity.** The flow must exist here, readable. A\n  new project is never bounded.\n- Unsure between two kinds: take the heavier. Complexity found mid-task upgrades the kind — stop and\n  say so. Nothing downgrades.\n\n## The artifact scales, the approval does not\n\n- A bounded design may be three sentences. It still ends with the human saying yes, and nothing is\n  implemented until then. Presenting a design and starting on it in one message skips the gate.\n- \"Too simple to need approval\" is where an unexamined assumption costs most — nobody looks twice.\n- **Exception:** a request that already names what to change and where — a function, a behavior, a\n  file — *is* the approved design. Asking to approve it is ceremony.\n\n## Understand before asking\n\n- **Read before you ask** — files, docs, recent commits. Do not spend the human's attention on what\n  the code answers.\n- **Launch a survey as you start reading:** `vvkit:architecture-surveyor` in the background, with a\n  file path for its report. It looks sideways — sibling features, type owners, how an abstraction was\n  last extended. Read it before proposing. Skip only for a one-sentence change.\n- **Check the scope.** Several independent subsystems: name the pieces and their order, design the\n  first.\n- **One question per message**, multiple choice where possible. Five questions get the easy ones\n  answered.\n- **Ask about purpose, constraints and what done looks like** — not details the design settles.\n- **Write your understanding back**: outcome, constraints, success — what the human said kept apart\n  from what you assumed. Invite correction. If the request already states it all, reflect it back.\n\n## Say the premises out loud\n\n- A premise is what was already true and nobody said. Nothing checks it, so rounds of careful design\n  on a wrong one deliver the wrong thing more convincingly each time.\n- Ask **what would have to be true for this to be the right approach?** — who needs it, what the\n  problem costs today, what it is assumed to be free of. Write the answers in the note.\n- Measure a premise that is cheap to measure. Compensation code for an unmeasured problem is the\n  typical casualty.\n- **Premises stay live after approval.** Re-read them when fixes keep landing on new variants of one\n  problem, or when work goes unusually smoothly.\n\n## Shape the design\n\n- **Data shape first.** Get the types and their states right before the logic; make illegal states\n  unrepresentable rather than checked for.\n- **Parse at the boundary, trust inside.** Validate outside data once, where it enters; keep business\n  logic in pure functions behind that boundary.\n- **Redesign, do not bolt on.** Ask what you would have built had the requirement been there from the\n  start; deliver that in pieces. A requirement bolted onto the old shape leaves both shapes behind.\n- **Subtract before you add.** Look for complexity the change lets you remove first.\n- **Operations that can be retried or interrupted are idempotent** — run twice, or after a crash\n  halfway, they end in the same state.\n- **Shared mutable state gets one writer**, enforced by the structure. If two parts do not need the\n  same mutable thing, give each its own.\n- **Extend, never disguise data.** A function that takes another type is asking for a sibling that\n  takes yours. Hand-building another layer's type from data that never came from there invents fields\n  everything downstream trusts.\n- In an existing codebase, follow its patterns. Improve what the change touches when it gets in the\n  way; propose nothing that does not serve the goal.\n\n## Offer approaches, then present in sections\n\n- Two or three approaches with trade-offs, recommended one first, with why. One design turns review\n  into approve-or-reject.\n- Strip every feature nobody asked for. A design is easier to extend than to cut back.\n- Present in sections sized to difficulty, confirming each. A wall of design gets approved in one skim.\n- Mark each choice a **decision** (weighed against a named alternative) or a **default** (something had\n  to be picked). An unmarked default soon looks like a property of the problem.\n- Cover boundaries, data flow, failure behavior and testing. Each unit: what it does, how it is used,\n  what it depends on. A unit you cannot understand without its internals has its boundary misplaced.\n\n## Write it down when it is architectural\n\n- Save it where the project keeps designs. None named: `.agents\u002Fplans\u002F`, only if\n  `git check-ignore -q .agents\u002Fplans` succeeds; otherwise ask.\n- Reread for placeholders or \"TBD\", contradicting sections, a requirement readable two ways (pick one,\n  say which), and scope too large for one plan.\n- Ask the human to review the file. The plan follows — `vvkit:planning-changes`.\n- **Each approval covers the stage shown, nothing after it.** Agreement in chat permits writing the\n  design; an approved design permits the plan; an approved plan, with how it runs, permits code.\n  Resume at the earliest unapproved stage. Reading code is allowed at any stage.\n\n## Before implementing\n\n- [ ] The kind was stated, and the human could correct it\n- [ ] Your understanding was written back, assumptions marked, corrected where wrong\n- [ ] The human said yes to the design, after seeing it\n- [ ] Every open question that changes the design has an answer\n- [ ] Nothing in the design goes beyond what was asked\n- [ ] For architectural work, the design is written, reviewed, and a plan approved\n",{"name":5,"description":7},"main","cc22a222a76add5759a2df5fadf231a758691db5","skills\u002Fdesigning-changes","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy","Senior iOS engineer. Architecture, SDKs and apps for iOS, tvOS and watchOS.","2026-11-13 19:10:29",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add vadimvitvickiy\u002Fvv-agent-kit --skill designing-changes",{"tool":37,"command":38},"bunx","bunx skills add vadimvitvickiy\u002Fvv-agent-kit --skill designing-changes",{"tool":40,"command":41},"pnpm","pnpm dlx skills add vadimvitvickiy\u002Fvv-agent-kit --skill designing-changes","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fdesigning-changes\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M7B3JN7VG0YJ4JB8RP6HYZSJ","no-heading","Use when proving that the validator rejects a body with no H1 and a force-loading @-link.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fno-heading\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7B3JJMEW4E710ZG6HYJ7BWV","wrong-name-does-not-match-dir","Dispatches a subagent per task and reviews between each one.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fbroken-skill\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7B3JGE9MFT1HRP41YRVKN97","writing-tests","Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-tests\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7B3JD5X32VEBDBN7HB8E17Z","writing-skills","Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7B3J992MZH2QVZRED0DRPD9","writing-project-instructions","Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-project-instructions\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7B3J55C5WPWN20QXP9ET848","writing-logs","Use when adding or reviewing log statements, or when deciding what level a message belongs at.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-logs\u002FSKILL.md",[],[]]