[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71FEAWPC8BM27EE0A90VT8T":3,"skill-same:01M71FEAWPC8BM27EE0A90VT8T":101},{"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":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":14,"repositoryHtmlUrl":60,"repositoryHomepageUrl":6,"ownerHtmlUrl":61,"ownerBlogUrl":62,"ownerDescription":63,"updatedAt":64,"install":65,"resources":78},"01M71FEAWPC8BM27EE0A90VT8T","righting-software-system-design",null,"Opt-in, collaborative system-design workflow based on Juval Löwy's iDesign methodology in *Righting Software*. Conducts a multi-phase interview (framing → use cases → volatility analysis → components → call-chain validation → report) that surfaces unknown-unknowns and produces a written recommendation at `decompositions\u002F{system-name}\u002Freport.md`. **Run only when the user explicitly invites this workflow** — not for general architecture questions, lightweight design conversations, or quick \"where should X live?\" questions. Valid triggers: the user names the skill directly, references *Righting Software* \u002F Juval Löwy \u002F iDesign \u002F \"The Method\" \u002F volatility-based decomposition and asks to run a full session, asks for a \"deep\" or \"structured\" or \"Löwy-style\" system design session, or accepts a prior suggestion to run it. Wait for an explicit yes before entering Phase 0. The skill is interrogative — a back-and-forth interview that challenges each volatility candidate and proposes ones the user hasn't considered.","esond\u002Fskills","esond","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4650644?v=4","01M71FCJGKDH30JSHK6XJZXN8Y","Eric Sondergard","01M71FCJHP4WCJVP4HVMEW1KB2",0,"MIT","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"design","software","system","righting software","righting software system design","system design","full","live","wait","at","run","valid","phase","architecture","candidate","components","unknown","wait for","quick","deep","2026-11-10 10:12:30",false,"---\nname: righting-software-system-design\ndescription: >-\n  Opt-in, collaborative system-design workflow based on Juval Löwy's iDesign\n  methodology in *Righting Software*. Conducts a multi-phase interview\n  (framing → use cases → volatility analysis → components → call-chain\n  validation → report) that surfaces unknown-unknowns and produces a written\n  recommendation at `decompositions\u002F{system-name}\u002Freport.md`. **Run only when\n  the user explicitly invites this workflow** — not for general architecture\n  questions, lightweight design conversations, or quick \"where should X live?\"\n  questions. Valid triggers: the user names the skill directly, references\n  *Righting Software* \u002F Juval Löwy \u002F iDesign \u002F \"The Method\" \u002F volatility-based\n  decomposition and asks to run a full session, asks for a \"deep\" or\n  \"structured\" or \"Löwy-style\" system design session, or accepts a prior\n  suggestion to run it. Wait for an explicit yes before entering Phase 0. The\n  skill is interrogative — a back-and-forth interview that challenges each\n  volatility candidate and proposes ones the user hasn't considered.\n---\n\n# Righting Software: System Decomposition\n\nA collaborative iDesign decomposition session faithful to Juval Löwy's\n*Righting Software*. The skill conducts a turn-by-turn interview that\nestablishes business framing, identifies core use cases, interrogatively\nsurfaces volatility, maps it to the iDesign service hierarchy\n(Manager → Engine → ResourceAccess → Resource + Utilities), and validates\nthe result by composing call chains for each core use case.\n\nThe deeper goal — beyond producing a clean architecture — is to **help the\nuser surface unknown-unknowns** about their own system. The volatility\ndiscovery techniques here (solutions-masquerading-as-requirements,\ndesign-for-your-competitors, volatility-and-longevity, the anti-design\neffort) are themselves tools for finding what the user didn't know to ask.\nUse them actively; don't wait for the user to volunteer the right\ninformation.\n\n## When to run this skill (opt-in only)\n\nThis is a **heavyweight, multi-hour workflow**. It is not the default\non-ramp for architecture conversations. Most \"where should this live?\"\nor \"should I split this service?\" questions deserve a normal\nconversation, not this entire process.\n\n**Run this skill only when the user has explicitly invited it.** That\nmeans one of:\n\n- The user named the skill (`righting-software-system-design`) or\n  asked for it by reference\n- The user referenced the source material (*Righting Software*, Juval\n  Löwy, iDesign, \"The Method\", volatility-based decomposition) AND\n  asked to go through it\n- The user accepted a prior suggestion from the agent to run this\n  workflow\n\n**It is appropriate to *suggest* this skill** when the user's question\nis genuinely heavy enough to warrant it — a clean-slate new system, a\nmonolith-to-services extraction, or recurring \"every change touches\neverything\" pain that has resisted lighter analysis. Frame the\nsuggestion clearly: *\"There's a guided volatility-based decomposition\nworkflow (a few hours of back-and-forth, produces a written report).\nWant to run it, or would you rather just talk through this informally?\"*\n\nIf the user declines or wants something lighter, **don't run this\nskill**. Have the normal conversation instead. This workflow earns its\nweight on the right problems and drowns lighter ones.\n\nOnce the user opts in, proceed to *Starting a session* below.\n\n## Dependencies\n\nThe skill has one optional-but-recommended external dependency:\n\n- **[D2](https:\u002F\u002Fd2lang.com)** (CLI, free single binary) — used in\n  Phase 5 to render the final architecture and call-chain diagrams.\n  Without it, the skill falls back to embedded hand-written SVG, which\n  produces the same visual output but with more verbose source.\n  Install via `winget install terrastruct.d2` (Windows),\n  `brew install d2` (macOS), or download from \u003Chttps:\u002F\u002Fd2lang.com>.\n\nPhases 0–4 use only Mermaid (renders in any markdown viewer), so D2 is\nnot required to start a session — only to produce the final report's\npolished diagrams. The skill will check D2 availability when it reaches\nPhase 5 and tell the user once if it's missing, then continue with the\nSVG fallback.\n\n## The first principles (non-negotiable)\n\nThese four rules govern every decision in the session. Refer back to them\nconstantly.\n\n1. **Decompose by volatility, not functionality.** Every component must\n   answer: *what single axis of change does this encapsulate?* If the\n   answer is a verb or use-case step (Validate, Price, Ship, Notify), the\n   boundary is functional and wrong. If the answer is a crisp axis of\n   change (tax law, partner API, pricing rule, regulator), the boundary\n   is correct.\n\n2. **There is no feature.** Features are always and everywhere aspects\n   of *integration*, not implementation. The system supports a use case\n   by integrating components — never by housing the use case in a\n   component named after it. If the user asks \"where does feature X\n   live?\", the correct answer is always a call chain across components,\n   never a single component.\n\n3. **Never design against the requirements.** Requirements change.\n   Design against the smallest set of components that supports all\n   *core* use cases through different compositions. When requirements\n   change, the composition (Manager workflow code) changes — not the\n   decomposition.\n\n4. **Strive for the smallest set.** The architect's mission is the\n   smallest set of components that can compose to support every core use\n   case. Typical well-designed systems land at ~10–20 components total\n   (2–5 Managers, 2–3 Engines, 3–8 ResourceAccess + Resources, ~6\n   Utilities). A 1-component design is unvalidatable; a 100-component\n   design is functional decomposition.\n\n## How to run this interview\n\nThis skill is not a generator — it is a Socratic interview. The shape of\neach turn:\n\n- **Ask, then deepen.** When the user answers, follow up. \"What changes\n  when that changes?\" \"Why is that volatile?\" \"Has it actually changed,\n  or could it?\" Surface assumptions, contradictions, and what's missing.\n- **Reflect and paraphrase.** Restate what you heard before moving on.\n  This catches misinterpretation early and signals you're listening.\n- **Propose, don't only ask.** Use your domain knowledge to suggest\n  candidate volatilities the user didn't mention. *\"Most marketplaces of\n  this shape eventually see X — does that apply here?\"* This is the\n  primary unknown-unknowns surfacing move.\n- **Challenge candidates.** Every proposed volatility must answer: what\n  exactly is volatile, why is it volatile, what's the likelihood and\n  effect of change, and could it be a sub-attribute of something else?\n  Reject candidates that are merely variable or speculative.\n- **Ask with a structured choice at branches.** When the user faces a\n  discrete choice (new vs. refactor, encapsulate vs. fold-in, which Manager\n  owns X), present 2–4 options with brief reasoning rather than open prose\n  (Claude Code: `AskUserQuestion`; otherwise a numbered list).\n- **Stop and check in between phases.** Never proceed to the next phase\n  without an explicit \"looks good, continue\" from the user.\n\nThe user is the domain expert; you are the methodology expert. The job\nis to apply Löwy's rules to their context, not to teach iDesign as a\nlecture.\n\n## Starting a session\n\nBefore anything else, suggest a short kebab-case name for the system\nbeing decomposed. *\"I'm trying to figure out how to structure our order\npipeline\"* → suggest `order-pipeline`. Let the user override.\n\nThen ask, as a structured choice:\n\n> **Is this a new system or a refactor of an existing one?**\n>\n> - New system — greenfield, no legacy\n> - Refactor — existing system being restructured\n\nThe methodology is identical either way, but the final report differs\n(greenfield gets a build sequence; refactor gets a current-→-target\nmapping with extraction priorities).\n\nAll persistent artifacts live in `decompositions\u002F{system-name}\u002F`:\n\n| File                                          | Purpose                                            |\n|-----------------------------------------------|----------------------------------------------------|\n| `decompositions\u002F{system-name}\u002Freport.md`      | The growing recommendation report — the headline artifact |\n| `decompositions\u002F{system-name}\u002Fuse-cases.md`   | (Optional) raw use cases with swim lanes, if they grow long |\n\nWrite everything important to `report.md` as the session progresses.\nChat is the conversation surface; the file is the durable record.\n\nIf a decomposition was previously run on this system, pick\na distinct system name (`order-pipeline-v2`, `order-pipeline-rework`,\netc.) so the prior report isn't overwritten. The directory layout is\nintentional: each session gets its own `decompositions\u002F{system-name}\u002F`\nsubtree.\n\n---\n\n## Phase 0: Framing — Vision, Objectives, Mission\n\n**Goal**: Establish the business framing that *compels* volatility-based\ndecomposition. This phase exists because Löwy's hardest political problem\nis getting management to accept the methodology — and the trick is to\nhave the business itself instruct the architect to design correctly.\n\nWithout this framing, the rest of the session produces a defensible\ndesign that the org will still reject. With it, the design is the\nbusiness's logical conclusion.\n\n### Step 0a: The Vision\n\nAsk: **\"In one sentence, what is this system?\"**\n\nPush for terseness. *\"Read it like a legal statement.\"* A good vision is\none sentence, business-perspective, no implementation language.\n\n**Examples from the book:**\n- TradeMe: *\"A platform for building applications to support the TradeMe marketplace.\"*\n\nIf the user gives a paragraph, distill it together. If the user gives a\nfeature list, push back — features are not vision.\n\n### Step 0b: The Business Objectives\n\nAsk: **\"What does the business need from this system? Itemize.\"**\n\nRules:\n- Business perspective only. Reject technology objectives (\"use Kubernetes\"),\n  marketing objectives (\"look better than competitor X\"), and specific\n  requirements (\"send an email when …\").\n- Each objective must serve the vision. Reject anything that doesn't.\n- Aim for 3–8 objectives.\n\nIf the user lists fewer than three, probe: *\"What about scalability?\nLocalization? Compliance? Speed of feature delivery? Audit\ntrails? Recovery from incidents?\"* — propose candidates from common\nbusiness concerns.\n\n### Step 0c: The Mission Statement\n\nThis is the most important sentence in the whole session.\n\nDraft: **\"Design and build a collection of software components that the\ndevelopment team can assemble into applications and features.\"**\n\nAdjust the wording to the user's context, but preserve the structure:\nthe mission is to build **components** that **compose** into features —\nNOT to build the features themselves. This is the rhetorical move that\nmakes volatility-based decomposition the business's idea.\n\n### Step 0d: Write the framing\n\nAdd a `## Framing` section to `report.md` with the vision, the\nobjectives (as a numbered list), and the mission statement. End the\nsection with the chain:\n\n> Vision → Objectives → Mission Statement → Architecture\n\n**Stop and check in**:\n\n> \"Here's the framing. Does the mission statement actually capture how\n> you want the team to think about this system? Anything missing from\n> the objectives? Once you're happy, we'll move to use cases.\"\n\nWait for the user.\n\n---\n\n## Phase 1: Use Cases & Glossary\n\n**Goal**: Capture the required *behaviors* (not functionalities) of the\nsystem, identify the small number of **core use cases**, and build a\nshared glossary. This phase is where the user's mental model becomes\nvisible.\n\n### Step 1a: Gather raw use cases\n\nAsk: **\"Walk me through how the system will be used. Don't worry about\norder or completeness yet — just what needs to happen.\"**\n\nCapture each as a short list with: trigger, primary actor, sequence,\noutcome, error paths. Use plain text — diagrams come later if needed.\n\n**Surface unknown-unknowns aggressively here.** Löwy's quote: *\"the\nusers interact with or observe just a small part of the system, which\nrepresents the tip of the iceberg. The bulk of the system remains below\nthe waterline.\"* Probe for:\n- **Background processes** — schedulers, timers, batch jobs, reconciliations\n- **Admin \u002F operator use cases** — system administrators, support staff\n- **External-system-triggered use cases** — webhooks, partner callbacks\n- **Error and recovery paths** — refunds, reversals, retries, manual intervention\n- **Reporting and audit** — compliance, business intelligence, monitoring\n- **Long-running flows** — anything that spans multiple sessions \u002F devices \u002F days\n\nPropose candidates from your knowledge of similar systems. *\"In most\nmarketplace systems I've seen, there's also a dispute resolution flow.\nDoes that apply here?\"*\n\n### Step 1b: Swim lanes\n\nFor any use case involving multiple roles or subsystems, redraw it as an\nactivity diagram with **swim lanes** — one lane per role\u002Fentity (Client,\nMember, Market, Regulator, etc.). This isn't decoration; the swim lanes\nthemselves become candidate subsystem boundaries in Phase 3.\n\nIf the lanes are obvious from text, you can describe them; if not,\nsketch a Mermaid `flowchart` or just a structured outline.\n\n### Step 1c: The glossary (Four Questions)\n\nBuild a glossary by answering the **Four Questions**:\n\n| Question | What it captures |\n|----------|------------------|\n| **Who** | Actors — users, external systems, schedulers |\n| **What** | Top-level required behaviors \u002F capabilities |\n| **How** | Activities the system performs (the verbs) |\n| **Where** | Data and external dependencies — where state lives |\n\nThese map roughly to architectural layers later (Who→Clients,\nWhat→Managers, How→Engines + ResourceAccess, Where→Resources). The\n**What** list especially hints at subsystem boundaries.\n\n### Step 1d: Identify the core use cases\n\nThis is the most consequential step in Phase 1.\n\n> \"Most systems have 2–6 core use cases. The rest are variations.\n> Looking at what we've collected, which use cases capture the *essence\n> of the business*? If this system did nothing else, which would still\n> need to work?\"\n\nThe core use cases:\n- Are usually **abstractions** of the listed use cases — may need a new name\n- Are rarely explicit in any requirements doc\n- Tend to be 2–6; if the user names more than 6, push back: are these\n  really distinct, or variations?\n- Hint: count the bullets on a one-page marketing brochure for the system\n\n**Example from TradeMe**: of ~8 listed use cases (Add Tradesman, Request\nTradesman, Match, Assign, Terminate, Pay, Create Project, Close\nProject), only **Match Tradesman** is a core use case. The rest are\nplumbing.\n\n### Step 1e: Write Phase 1\n\nAdd to `report.md`:\n- `## Glossary` (Four Questions)\n- `## Use Cases` — list with brief sequences\n- `## Core Use Cases` — the 2–6, with a short paragraph each explaining\n  why this captures the essence\n\nIf use cases grow long, split them into `use-cases.md` and link.\n\n**Stop and check in**:\n\n> \"I've documented use cases and called out what I think are the core\n> ones. Read through and tell me: are the core use cases actually core?\n> Anything I've missed below the waterline? Once we agree on the cores,\n> we'll dig into volatility.\"\n\nWait for the user.\n\n---\n\n## Phase 2: Volatility Analysis\n\n**Goal**: Identify what's actually volatile (and what isn't), through\nchallenge and discovery rather than passive elicitation. This is the\nphase where unknown-unknowns are most likely to surface.\n\nThis phase produces a **Volatilities List** — candidate areas of change\nwith rationale. It does not yet name components.\n\n### Step 2a: The two axes of volatility\n\nLöwy defines exactly **two axes**:\n\n1. **Same customer over time** — even if the system perfectly fits one\n   customer today, that customer's context will change.\n2. **Different customers at the same point in time** — across the\n   customer base today, who uses the system differently?\n\nThe axes should be **independent**. If a candidate volatility can't be\ncleanly assigned to one axis or the other, that's a signal of\nfunctional decomposition in disguise — investigate further.\n\n> Note: you may have seen \"five axes\" frameworks (requirements \u002F\n> technology \u002F integration \u002F data \u002F policy) elsewhere. That isn't from\n> *Righting Software* — Löwy's book defines only the two axes above.\n> The five categories can be useful prompts during Step 2c (axes\n> sweep), but they aren't the framework.\n\n### Step 2b: Volatile vs. Variable\n\nBefore listing any volatility, share this distinction with the user:\n\n> **Variable**: something that changes but is handled in code with\n> conditional logic. Adding a new attribute to a customer record is\n> variable.\n>\n> **Volatile**: something open-ended whose changes ripple across the\n> system unless encapsulated. Swapping payment providers is volatile.\n\n**Only encapsulate volatility, not variability.** Most candidates the\nuser volunteers will be variability. Filter ruthlessly.\n\n### Step 2c: Surface candidates through multiple lenses\n\nDon't just ask \"what changes?\" — that gets opinions. Use these lenses\nto *discover* volatility the user hadn't named:\n\n1. **Change history**: *\"In the last 1–2 years, what changed in this\n   system or its predecessor, and why? Group changes by reason.\"*\n2. **Roadmap**: *\"What's planned for the next 6–12 months? What's been\n   discussed but not committed?\"*\n3. **The longevity heuristic** (powerful for surfacing missed\n   volatilities): *\"How long do you expect this system to be in\n   service? Now look back the same number of years — what changed in\n   that window? Whatever changed before will likely change again.\"*\n4. **Design for your competitors**: *\"Could your direct competitor use\n   this system as-is? Where would they need it to behave differently?\"*\n   Differences expose volatility; sameness exposes nature-of-business.\n5. **Solutions masquerading as requirements** (see Step 2d).\n6. **Anti-design contrast**: walk through a deliberately-bad\n   functional or domain decomposition; the points of pain it exposes\n   are often volatility you'd otherwise miss.\n7. **The agent proposes**: based on the domain (payments, marketplace,\n   logistics, SaaS, etc.), suggest 3–5 common volatilities for that\n   class of system the user hasn't mentioned. Present the candidates as\n   a structured choice if helpful.\n\n### Step 2d: Peel solutions-masquerading-as-requirements\n\nThis is Löwy's primary volatility-discovery technique. Many \"requirements\"\nthe user states are actually solutions to a deeper need. Peel them\nrecursively:\n\n> *\"Send an email confirmation.\"* → real requirement is **notify**\n> (could be email, SMS, push). Volatility: notification transport.\n>\n> *\"Cooking in the kitchen.\"* → real requirement is **feed the\n> occupants**. → real-real requirement is **occupants' well-being**.\n\nFor each candidate volatility, ask:\n1. Is this a solution or a real requirement?\n2. What other solutions could satisfy the same need?\n3. What's the *underlying* volatility?\n\n### Step 2e: Filter — what NOT to encapsulate\n\nVolatility-based decomposition can be over-applied. Reject candidates\nthat fail any of these tests:\n\n- **Nature of the business**: does it relate to what the company\n  fundamentally does? Two indicators: (a) change is rare,\n  (b) any attempt to encapsulate it would be done poorly given\n  available resources. *Don't encapsulate the nature of the business.*\n  (FedEx → Healthcare branch ≠ a volatility to encapsulate.)\n- **Speculative**: is the change extremely unlikely AND would the\n  encapsulation only be done poorly? Reject (the SCUBA-ready high\n  heels test).\n- **Merely variable**: handled by conditionals; no ripple effect.\n- **Out of scope**: the volatility is real, but it's owned by an\n  external Resource (e.g., an external payment system's internal\n  volatility).\n\nWhen rejecting a candidate, **state the rejection reason explicitly** in\nthe report. The user should be able to defend each rejection later.\n\n### Step 2f: Cluster and challenge\n\nFor each surviving candidate, document:\n- A name (just descriptive, not a component name yet)\n- What changes\n- Why (the underlying driver)\n- Which axis (or both)\n- Ripple radius — \"if this changes, what else has to change with it?\"\n\nActivities that change for the *same reason* belong together;\nactivities that change for *different reasons* belong apart, even if\nthey look related.\n\nThis list is the input to Phase 3, which is where components get\nnamed. A single component will often own several entries from this\nlist when they ripple together (e.g., a Manager owning the workflow\nvolatility of a whole use-case family), though a component owning one\nstandalone axis is also valid. Cluster axes here when they share a\nreason for change — that's exactly what this step is for — but don't\nassign component boundaries yet. Leave each clustered axis named so\nthe report's audit trail from volatilities to components stays\nintact, and let Phase 3 decide which clusters become which\ncomponents.\n\n### Step 2g: Write Phase 2\n\nAdd a `## Volatility Analysis` section to `report.md`:\n- Short paragraph per major volatility, with the why\n- Table of candidate volatility clusters\n- An **explicit list of rejected candidates** with rejection reasons\n\n```markdown\n### Rejected as not architecturally volatile\n\n| Candidate          | Reason                                                          |\n|--------------------|-----------------------------------------------------------------|\n| Adding new fields to a tradesman record | Variable, not volatile — handled by schema migration |\n| Branching into healthcare staffing      | Nature of the business — would redefine the company |\n| Optimization algorithms for project matching | Speculative — company isn't in the optimization business |\n```\n\n**Stop and check in**:\n\n> \"Here's the volatility analysis with the candidates I've accepted and\n> rejected. The rejections are as important as the accepts — challenge\n> any of them you disagree with. Anything I've split that should be\n> merged, merged that should be split, or missed entirely?\"\n\nWait for the user. Expect to iterate here.\n\nFor deeper coverage of volatility-discovery techniques, see\n`references\u002Fvolatility-techniques.md`.\n\n---\n\n## Phase 3: Component Definition\n\n**Goal**: Map the validated volatility list to the iDesign service\nhierarchy, using the Four Questions as a check.\n\n### Volatility-to-component mapping isn't 1:1\n\nA component can encapsulate one volatility or several. Both are valid;\nthe choice depends on whether the volatilities genuinely ripple\ntogether. *Righting Software* is explicit that many-to-one is common —\nthe TradeMe `MarketManager` owns three volatilities (managing projects,\nmatching tradesmen to projects, charging fees for the match) because\nthey're a family of logically related use cases sharing one\nworkflow-sequence axis. The same book also shows single-volatility\nManagers: TradeMe's `EducationManager` encapsulates only the education\nworkflow, with searching and regulatory compliance pushed to other\ncomponents.\n\nThere's a **directional bias toward consolidation**, driven by the\nsmallest-set principle (first principles #4). The book frames this as\nminimizing the amount of work in detailed design and implementation:\n1 component is too few (a monolith hides complexity inside) and 300\ncomponents is too many (integration cost explodes). The right answer\nlives around an order of magnitude of 10. The bias has a hard limit:\n**cohesion**. Volatilities that change for related reasons belong\ntogether; volatilities that change for unrelated reasons stay apart\neven when merging them would lower the count. Cramming unrelated axes\ninto one component isn't consolidation — it's functional decomposition\nwith a smaller N.\n\nCommon shapes (per *Righting Software*, Ch. 3 and Ch. 5):\n\n- A **Manager** often owns the sequence volatility of a *family* of\n  related use cases — frequently 2–4 listed volatilities sharing the\n  same workflow-orchestration axis. A Manager owning one volatility is\n  also valid when no other workflow family is related enough to share\n  orchestration with it (e.g., TradeMe's `EducationManager`).\n- An **Engine** has more restricted scope than a Manager, encapsulating\n  business rules and activities. Single-axis Engines are normal; the\n  book's `RegulationEngine` and `SearchEngine` are each one activity\n  volatility.\n- A **ResourceAccess** typically owns *both* the volatility of how the\n  Resource is accessed AND volatility of the Resource itself —\n  *\"Resource changes invariably change ResourceAccess as well\"* (Löwy).\n  Splitting these into separate components is a common\n  over-decomposition mistake.\n\nIf your Phase 2 list has 15 volatilities and your Phase 3 proposal has\n15 components, the design probably hasn't done any consolidation work —\nlook for related axes that could share a component. But don't force\nmerges; an N-to-N mapping that genuinely reflects N unrelated axes is\nbetter than a low count built on weak cohesion.\n\n### The hierarchy\n\n| Type             | Encapsulates                                              | Calls       |\n|------------------|-----------------------------------------------------------|-------------|\n| **Clients**      | Volatility in entry points (UIs, APIs, schedulers)        | Managers    |\n| **Managers**     | Volatility in the *sequence* \u002F workflow of use cases      | Engines, ResourceAccess, Utilities |\n| **Engines**      | Volatility in *activities* — business rules, calculations | ResourceAccess, Utilities |\n| **ResourceAccess** | Volatility in *how* a Resource is accessed AND in the Resource itself | Resources, Utilities |\n| **Resources**    | The actual data\u002Fexternal systems (DB, cache, external APIs) | —         |\n| **Utilities**    | Cross-cutting infrastructure (Logging, Security, Pub\u002FSub) | (anyone, via the utility bar) |\n\n### The Four Questions check\n\nMap each volatility to a question, and the question to a layer:\n\n| Question | Layer |\n|----------|-------|\n| **Who** interacts with the system? | Clients |\n| **What** is required of the system? | Managers |\n| **How** does the system perform business activities? | Engines |\n| **How** does the system access resources? | ResourceAccess |\n| **Where** does the system's state live? | Resources |\n\nIf a candidate component doesn't crisply answer one question, you've\neither picked the wrong layer or missed a volatility.\n\n### Closed architecture rules\n\nCalls go top-down only. Allowed:\n- Client → Manager\n- Manager → Engine\n- Manager → ResourceAccess (Engines are optional; Managers can call Access directly when there's no activity volatility to encapsulate)\n- Engine → ResourceAccess\n- Any layer → Utilities (the vertical bar)\n- ResourceAccess → Resources\n\nForbidden:\n- Sideways calls (Manager → Manager, Engine → Engine, ResourceAccess → ResourceAccess)\n- Calling up (Engine → Manager, Manager → Client)\n- Skip-level down (Manager → Resource, Client → Engine)\n- Clients calling multiple Managers in a single use case (sign of functional decomp)\n\nAllowed relaxations:\n- **Queued Manager → Manager** via a Pub\u002FSub or Message Bus utility (technically a downward call through Access; semantically a deferred second use case)\n- **Manager → Pub\u002FSub utility → other Managers** for fan-out (instead of sideways calls)\n\nSee `references\u002Fanti-patterns.md` for the full design-don'ts catalog.\n\n### Naming conventions\n\nTwo-part Pascal-case compound words. **Suffix = service type**:\n\n| Type             | Suffix         | Prefix                                              | Examples                                |\n|------------------|----------------|-----------------------------------------------------|-----------------------------------------|\n| Manager          | `Manager`      | Noun — the volatility encapsulated in the use cases | `MembershipManager`, `MarketManager`    |\n| Engine           | `Engine`       | Noun OR gerund — the encapsulated activity          | `SearchEngine`, `RegulationEngine`, `CalculatingEngine` |\n| ResourceAccess   | `Access`       | Noun — the Resource \u002F data                          | `MembersAccess`, `PaymentsAccess`, `WorkflowsAccess` |\n| Utility          | (varies)       | The cross-cutting concern                           | `Logger`, `Security`, `MessageBus`      |\n\n**Critical naming rules:**\n- The ResourceAccess suffix is `Access`, not `Accessor`. (Common\n  community mistake.)\n- **Gerunds belong only in Engines.** A gerund anywhere else\n  (`BillingManager`, `BillingAccess`) signals functional decomposition.\n- **Atomic business verbs never appear in prefixes.** Verbs like\n  `Credit`, `Debit`, `Pay` are operation names *on contracts*, not\n  service prefixes.\n- Avoid functional names: `OrderProcessor`, `PaymentHandler`,\n  `NotificationSender` are use-case names. Rename to the volatility\n  axis.\n\n### Forbidden vocabulary at this stage\n\nInfrastructure names don't belong in component names: Lambda, ECS, SQS,\nDynamoDB, S3, Kubernetes, Docker, Postgres, Redis. These are deployment\nconcerns. A `LambdaInvoker` is decomposed by infrastructure, not\nvolatility. Push back and propose a volatility-axis name.\n\n### Heuristics for getting the count right\n\n- **Manager : Engine ratio** — roughly 2:1. 1 Manager → 0–1 Engines.\n  2 Managers → ~1 Engine. 3 Managers → ~2 Engines. 5 Managers → ~3\n  Engines. **8+ Managers = failed design** (you've done functional\n  decomp).\n- **Per subsystem** — at most 3 Managers. Subsystems are vertical\n  slices (one Manager + its Engines + its ResourceAccess). Most\n  systems have only a handful of subsystems.\n- **Total components** — usually 10–20 in a well-designed system.\n- **Engines are uncommon.** For an Engine to exist there must be real\n  activity volatility — an unknown number of ways of doing something.\n  Lots of Engines almost always means functional decomp at the Engine\n  layer.\n\n### Utilities litmus test\n\nA component qualifies as a Utility only if it could plausibly serve any\nother system, even one as different as a *smart cappuccino machine*.\n- ✅ Logger, Security, Pub\u002FSub, Diagnostics — yes\n- ❌ MortgageInterestCalculator — no, it's domain logic in disguise\n\n### Almost-expendable Managers\n\nFor each Manager, apply the test: **how would you respond to a request\nto change this Manager?**\n\n- *Fight it \u002F fear the cost* → \"expensive\" Manager — too big, almost\n  certainly functional decomp inside\n- *Shrug it off, easy change* → \"expendable\" Manager — pass-through, no\n  real volatility encapsulated, design flaw\n- *Thoughtfully estimate how to adapt the workflow* → **\"almost\n  expendable\"** — correct. The Manager orchestrates Engines and Access,\n  encapsulating only sequence volatility, and absorbs change in its\n  workflow code without architectural impact.\n\nAim for almost-expendable Managers. Flag any that fail.\n\n### Write the components\n\nAdd a `## Components` section to `report.md`. Lead with a Mermaid\nlayered diagram, then one table per tier.\n\n#### Diagram template\n\nClient → Manager → Engine → ResourceAccess → Resource stacked\ntop-to-bottom, Utilities as a vertical bar on the right consumed from\nany layer. Arrows at the layer level only; the per-component\nrelationships are implied by layer membership.\n\n```mermaid\nblock-beta\n  columns 2\n\n  block:main:1\n    columns 1\n\n    block:client[\"CLIENT\"]\n      columns 4\n      %% Entry points — web, API, scheduler, inbound webhooks\n      %% Fill in actual components and apply: class id1,id2 client\n    end\n\n    block:managers[\"MANAGERS\"]\n      columns 3\n      %% Workflow orchestrators — one per major workflow family\n      %% Apply: class id1,id2 manager\n    end\n\n    block:engines[\"ENGINES\"]\n      columns 5\n      %% Business logic, rules, calculations\n      %% Apply: class id1,id2 engine\n    end\n\n    block:accessors[\"RESOURCE ACCESS\"]\n      columns 4\n      %% Wrap data + external integrations; expose atomic business verbs\n      %% Apply: class id1,id2 access\n    end\n\n    block:resources[\"RESOURCES\"]\n      columns 5\n      %% Databases, partner APIs, external systems\n      %% Apply: class id1,id2 resource\n    end\n  end\n\n  block:utilities[\"UTILITIES\"]:1\n    columns 1\n    %% Cross-cutting infrastructure, consumed from any layer\n    %% Apply: class id1,id2 utility\n  end\n\n  classDef client   fill:#d1fae5,stroke:#1f2937\n  classDef manager  fill:#fef9c3,stroke:#1f2937\n  classDef engine   fill:#fed7aa,stroke:#1f2937\n  classDef access   fill:#e5e7eb,stroke:#1f2937\n  classDef resource fill:#dbeafe,stroke:#1f2937\n  classDef utility  fill:#f3e8ff,stroke:#1f2937\n```\n\n**No arrows on the static diagram.** Layer membership already conveys\nthe call direction (Managers above Engines means Managers call into\nEngines). Per-component arrows would clutter without adding\ninformation. Save arrows for the call-chain diagrams in Phase 4, where\nthey show the specific path of one use case.\n\n**Layer colors are consistent across every diagram in the session**\n(Mermaid here, D2 and SVG in Phase 5): green for Client, yellow for\nManagers, orange for Engines, grey for Access, light blue for\nResources, lavender for Utilities. The same component always uses the\nsame color and stays in the same row\u002Fcolumn position across all\ndiagrams — that's what makes the Phase 4 symmetry check legible.\n\nPopulate every layer with at least one block before rendering — some\n`block-beta` renderers drop the layer label on empty layers.\n\nIf a single layer has more than ~7 components, the system probably\nwants a subsystem split.\n\n#### Component tables\n\nBeneath the diagram:\n\nList **every volatility cluster** a component owns in the `Encapsulates`\ncolumn — don't compress a multi-volatility component into a single\nphrase. The audit trail back to Phase 2 only works if each accepted\nvolatility shows up somewhere.\n\n```markdown\n### Managers\n| Component      | Encapsulates (volatility clusters)                                                    | Notes |\n|----------------|---------------------------------------------------------------------------------------|-------|\n| MarketManager  | Managing projects; matching tradesmen to projects; charging fees for the match | Three logically related use-case families share one orchestrator; only sequence volatility lives here |\n| MembershipManager | Membership management (add\u002Fremove, benefits, discounts); dispute resolution | Two related but distinct workflow families under one orchestrator |\n| EducationManager  | Education workflow                                                           | Single-volatility Manager; no other workflow family shares its orchestration axis |\n\n### Engines\n| Component        | Encapsulates                                | Depends on                |\n|------------------|---------------------------------------------|---------------------------|\n| RegulationEngine | Regulatory rule volatility across locales   | RegulationsAccess         |\n| SearchEngine     | Match-algorithm volatility                  | MembersAccess, ProjectsAccess |\n\n### ResourceAccess\n| Component        | Encapsulates                                                                  | Atomic business verbs    |\n|------------------|-------------------------------------------------------------------------------|--------------------------|\n| PaymentsAccess   | Payment provider choice; payment storage backend; reconciliation protocol     | Pay, Refund, Reconcile   |\n\n### Resources\n| Component | Notes |\n|-----------|-------|\n| Members   | Member profiles, history |\n\n### Utilities\n| Component   | Encapsulates                  |\n|-------------|-------------------------------|\n| Logger      | Logging framework volatility  |\n| MessageBus  | Pub\u002FSub transport volatility  |\n| Security    | Auth\u002FAuthZ volatility         |\n```\n\n**ResourceAccess contracts**: list the atomic business verbs each one\nexposes (e.g., `Pay`, `Credit`, `Debit`, `Match`, `Reserve`). Do **not**\nlist CRUD\u002FIO operations (`Insert`, `Select`, `Read`, `Write`,\n`Open`) — those leak the Resource technology.\n\n**Stop and check in**:\n\n> \"Here's the component proposal. For each Manager, do the\n> almost-expendable test in your head: how do you feel about being\n> asked to change it? Walk through which names feel off, which\n> boundaries feel wrong, or where I've put something at the wrong\n> tier.\"\n\nWait for the user.\n\n---\n\n## Phase 4: Validation via Call Chains\n\n**Goal**: Prove the design is composable by producing one **call chain\ndiagram** per core use case, then checking for symmetry and\ncomposability across them.\n\nA decomposition that doesn't survive its own validation isn't\nvolatility-based — it's guesses with better names.\n\n### What a call chain is\n\nFor each core use case, draw the interaction:\n- Components appear in their layer positions (same layout as the static\n  diagram)\n- **Solid black arrows** = synchronous calls\n- **Dashed gray arrows** = queued \u002F asynchronous calls\n- The call chain *superimposes* on the layered diagram — don't redraw,\n  just highlight\n\nUse Mermaid `flowchart` here. Mermaid is the **iteration format** — it\nrenders inline in markdown, costs nothing to regenerate as the design\nshifts, and is good enough for the symmetry\u002Fcomposability checks in this\nphase. Final-report rendering switches to D2 or SVG in Phase 5; don't\nspend effort polishing diagrams here. Example:\n\n```mermaid\nflowchart TD\n  Client[Tradesman Portal]:::client\n  Bus[MessageBus]:::utility\n  Mgr[MembershipManager]:::manager\n  Eng[RegulationEngine]:::engine\n  AccM[MembersAccess]:::access\n  AccP[PaymentsAccess]:::access\n  Members[(Members)]:::resource\n  Payments[(Payments)]:::resource\n\n  Client -. queued .-> Bus\n  Bus --> Mgr\n  Mgr --> Eng\n  Mgr --> AccM\n  Mgr --> AccP\n  AccM --> Members\n  AccP --> Payments\n\n  classDef client   fill:#d1fae5,stroke:#1f2937\n  classDef manager  fill:#fef9c3,stroke:#1f2937\n  classDef engine   fill:#fed7aa,stroke:#1f2937\n  classDef access   fill:#e5e7eb,stroke:#1f2937\n  classDef resource fill:#dbeafe,stroke:#1f2937\n  classDef utility  fill:#f3e8ff,stroke:#1f2937\n```\n\nAdd a brief narrative under each diagram: which Manager owns the\nworkflow, what triggers it, what completes it.\n\n### Step 4a: Draw one chain per core use case\n\nProduce a call chain for **every core use case** identified in Phase 1.\nDon't validate non-core use cases here — those are variations, and the\ncore chains should compose to cover them.\n\n### Step 4b: Symmetry check\n\nLay the chains side by side and look for **structural similarity**.\n- Do all chains follow the same shape (Client → Bus → Manager → Engine → Access → Resource)?\n- Does every workflow end with a Pub\u002FSub publish, OR none of them do?\n- Are queued vs. synchronous call patterns consistent across use cases?\n\n**Asymmetry is a design smell.** If three core use cases publish an\nevent at the end and the fourth doesn't, ask: why is the fourth\ndifferent? What's missing or extra?\n\nLöwy's words: *\"Symmetry is so fundamental for good design that you\nshould generally see the same call patterns across Managers.\"*\n\n### Step 4c: Composability proof\n\nGenerate a **new hypothetical use case** — something the user didn't\nmention but could plausibly want — and demonstrate that the existing\ncomponents compose to support it without architectural change.\n\n> *\"What if you needed to add 'analyze projects from 2022–2024 for\n> profitability'? Walk me through the call chain using only the\n> components we already have.\"*\n\nIf this fails — if the new use case requires a new Manager or a layer\nviolation — the decomposition isn't composable enough, and you should\nreturn to Phase 2.\n\n### Step 4d: Ripple-radius check\n\nFor 3–5 plausible future changes (drawn from the roadmap, change\nhistory, and competitor framing in Phase 2), document which components\neach change would touch.\n\n- **Good**: each scenario touches 1–2 components\n- **Bad**: any scenario touches 3+ components → unencapsulated\n  volatility; revisit Phase 2\n\nWhen a scenario fails, don't paper over it. Tell the user:\n\n> \"This scenario blows past three components. That means we have an\n> axis of change that isn't encapsulated yet. Let me re-examine the\n> clusters.\"\n\nThen loop back to Phase 2.\n\n### Write Phase 4\n\nAdd a `## Validation` section to `report.md` containing:\n- One subsection per core use case, with the Mermaid call chain and a\n  short narrative\n- A \"Symmetry observations\" subsection\n- A \"Composability check\" subsection with the hypothetical\n- A \"Ripple-radius scenarios\" subsection (each scenario + components touched + ✅\u002F❌)\n\n**Stop and check in** once chains and scenarios all pass:\n\n> \"All call chains hold and the ripple-radius scenarios stay contained.\n> Ready to write the final recommendation, or do you want to add more\n> stress-test scenarios first?\"\n\n---\n\n## Phase 5: Recommendation Report\n\n**Goal**: Finalize `report.md` as a usable, handoff-ready artifact.\n\nThe framing, glossary, use cases, volatility analysis, components, and\nvalidation are already in the file from Phases 0–4. This phase adds:\n\n### Implementation sequence (new systems)\n\nFor greenfield, give a bottom-up build order:\n\n1. **Utilities first** — foundations, depend on nothing\n2. **Resources** — provisioned alongside Utilities\n3. **ResourceAccess** — depends only on Utilities and Resources\n4. **Engines** — depends on Access + Utilities\n5. **Managers** — orchestrate everything\n\nCall out which components need senior attention — typically the most\nvolatile ones, whose interfaces are the contract that must absorb\nfuture change.\n\n### Migration plan (refactors)\n\nFor existing systems, add a `## Current → Target` mapping:\n\n- For each target component, identify where the logic currently lives\n- Flag extraction priorities (which boundary hurts most today?)\n- Note coupling that must break first (shared databases, peer calls,\n  skip-level calls)\n- Recommend an extraction order that minimizes intermediate breakage\n- If the existing system has infrastructure-named components\n  (`LambdaInvoker`, `SQSQueueProcessor`, `RedisCache`), propose\n  volatility-axis renames as part of the mapping\n\n### Optional: Operational concepts\n\nIf the system warrants advanced run-time patterns (Message Bus,\nWorkflow Managers, Message-Is-The-Application), add an `## Operational\nConcepts` section. **These are optional and require organizational\nmaturity** — see `references\u002Foperational-concepts.md` for guidance on\nwhen to recommend them and when to leave them out.\n\nDefault position: do **not** recommend these unless the user's\nobjectives in Phase 0 specifically demand them (e.g., \"quick turnaround\nfor new features\", \"support deep customization across markets\",\n\"forward-looking integration\"). Otherwise, leave the run-time\ninteractions as direct synchronous calls and let the team mature into\nthe more elaborate patterns later.\n\n### Render polished diagrams\n\nBefore finalizing the report, regenerate the static architecture and\neach call chain in a higher-fidelity format. Mermaid is fine during\niteration but doesn't preserve component positions across diagrams,\nwhich makes the Phase 4 symmetry check hard to read visually.\n\n**Step A: Check `d2` availability**\n\n```bash\nd2 --version\n```\n\nIf the command succeeds, proceed to Step B. If it fails with\n\"command not found\", continue to Step C.\n\nIf you're on Windows and the user told you they just installed D2 but\nthe command isn't found, suggest restarting the shell to pick up the\nnew PATH before falling back.\n\n**Step B: Generate D2 source and render**\n\nWrite D2 source under `decompositions\u002F{system-name}\u002Fdiagrams\u002F`:\n- One `static.d2` for the layered architecture\n- One `callchain-{usecase-slug}.d2` per core use case (use the same\n  filename slug for every diagram referencing the use case)\n\nUse the canonical templates in `references\u002Fdiagram-templates.md`. The\ntemplates enforce a **stable component coordinate map** — the same\ncomponent always sits in the same row\u002Fcolumn across every diagram,\nwhich is what makes Phase 4's symmetry check easy to verify by eye.\n\nRender each:\n\n```bash\nd2 diagrams\u002Fstatic.d2 diagrams\u002Fstatic.svg\nd2 diagrams\u002Fcallchain-match-tradesman.d2 diagrams\u002Fcallchain-match-tradesman.svg\n```\n\nThen reference the rendered SVGs from `report.md` with relative paths:\n\n```markdown\n![Static architecture](diagrams\u002Fstatic.svg)\n![Match Tradesman call chain](diagrams\u002Fcallchain-match-tradesman.svg)\n```\n\n**Step C: `d2` not installed — pause or fall back**\n\nD2 is the preferred final format because it's **codified source that\ncan be modified after the fact**. The SVG fallback produces the same\nvisual output but is awkward to edit later (hand-tweaking SVG paths\nvs. editing readable D2 source).\n\nOffer two paths as a structured choice:\n\n> `d2` isn't on PATH, so the final diagrams can't be emitted in their\n> preferred (editable) form. Two options:\n>\n> 1. **Pause and install** — `winget install terrastruct.d2` (Windows)\n>    or `brew install d2` (macOS), then restart the shell and tell me\n>    to continue. This is the recommended path; D2 output is editable\n>    going forward.\n> 2. **Fall back to embedded SVG** — visually identical, but harder\n>    to modify after the report is written. Pick this only if D2\n>    install is genuinely not an option.\n\nIf the user picks option 1, stop and wait. When they resume, retry\nStep A.\n\nIf the user picks option 2, write SVG directly to `diagrams\u002F` using\nthe SVG templates in `references\u002Fdiagram-templates.md` (same\ncoordinate map, just emitted as SVG).\n\n**Don't mix formats in the final report.** Pick one and use it for\nthe static diagram and every call chain. Consistency is the point.\n\n### Open questions and risks\n\nSurface anything you couldn't resolve:\n- Volatility axes where evidence was thin\n- Components that passed validation but felt fragile\n- Assumptions that should be re-tested in 6 months\n- Areas where the user disagreed with the methodology — note the\n  disagreement, the user's reasoning, and the implication\n\n### Hand off\n\nTell the user:\n\n> \"`decompositions\u002F{system-name}\u002Freport.md` is the recommendation\n> (with raw use cases in `use-cases.md` if that file exists). It's\n> structured so you can hand it to a team to either build from or\n> refactor toward. Want me to draft an ADR or a kickoff doc from it,\n> or are we done?\"\n\n---\n\n## Reference: when to consult the extra material\n\nThis skill is mostly self-contained, but four reference files cover\ndeeper material that doesn't belong inline:\n\n- **`references\u002Fvolatility-techniques.md`** — extended techniques for\n  surfacing volatility (the anti-design effort, design factoring\n  iterations, design-for-your-competitors variants). Consult during\n  Phase 2 if the user is stuck or the candidate list feels thin.\n- **`references\u002Foperational-concepts.md`** — Message Bus,\n  Message-Is-The-Application pattern, Workflow Managers. Consult in\n  Phase 5 only if the Phase 0 objectives suggest advanced patterns are\n  warranted.\n- **`references\u002Fanti-patterns.md`** — full catalog of design \"don'ts\"\n  from the book (event publishing rules, queue rules, layer-call\n  rules). Consult during Phase 3 component definition and during Phase\n  4 validation as a checklist.\n- **`references\u002Fdiagram-templates.md`** — canonical component\n  coordinate map and source templates for both D2 and SVG output.\n  Consult in Phase 5 when rendering the final diagrams.\n\n---\n\n## Things not to do\n\n- **Don't lecture.** The user knows their domain; you know the\n  methodology. Apply the rules to their context.\n- **Don't skip Phase 0.** Skipping framing produces a defensible\n  design that the org will reject anyway.\n- **Don't analyze during Phase 1.** Use-case walkthroughs lose\n  information the moment you start proposing boundaries.\n- **Don't accept volatility candidates passively.** Challenge each\n  one with the volatile-vs-variable, solutions-masquerading,\n  nature-of-business, and longevity tests. The user proposed it doesn't\n  mean it survives.\n- **Don't skip validation.** Call chains are not optional decoration —\n  they are the proof that the decomposition is composable.\n- **Don't recommend operational concepts (Message Bus, MITA, Workflow\n  Managers) by default.** They require organizational maturity. Match\n  the recommendation to the Phase 0 objectives and the team's stated\n  capabilities.\n- **Don't let infrastructure names into component names.** Save those\n  for the deployment plan.\n- **Don't treat this skill as a one-shot generator.** The value is in\n  the back-and-forth — the user's reactions in Phases 2–4 are where the\n  decomposition actually gets right.\n- **Don't widen scope into deployment, technology choices, or org\n  structure.** Those come *after* the decomposition exists.\n- **Don't blend rejected and accepted volatility silently.** Reject\n  candidates explicitly with a stated reason in the report.\n- **Don't accept the user's first answer as final.** Use the\n  unknown-unknowns surfacing techniques (competitor framing, longevity\n  heuristic, candidate proposals from your domain knowledge) to push\n  past what the user already knew to say.\n","# Righting Software: System Decomposition\n\nA collaborative iDesign decomposition session faithful to Juval Löwy's\n*Righting Software*. The skill conducts a turn-by-turn interview that\nestablishes business framing, identifies core use cases, interrogatively\nsurfaces volatility, maps it to the iDesign service hierarchy\n(Manager → Engine → ResourceAccess → Resource + Utilities), and validates\nthe result by composing call chains for each core use case.\n\nThe deeper goal — beyond producing a clean architecture — is to **help the\nuser surface unknown-unknowns** about their own system. The volatility\ndiscovery techniques here (solutions-masquerading-as-requirements,\ndesign-for-your-competitors, volatility-and-longevity, the anti-design\neffort) are themselves tools for finding what the user didn't know to ask.\nUse them actively; don't wait for the user to volunteer the right\ninformation.\n\n## When to run this skill (opt-in only)\n\nThis is a **heavyweight, multi-hour workflow**. It is not the default\non-ramp for architecture conversations. Most \"where should this live?\"\nor \"should I split this service?\" questions deserve a normal\nconversation, not this entire process.\n\n**Run this skill only when the user has explicitly invited it.** That\nmeans one of:\n\n- The user named the skill (`righting-software-system-design`) or\n  asked for it by reference\n- The user referenced the source material (*Righting Software*, Juval\n  Löwy, iDesign, \"The Method\", volatility-based decomposition) AND\n  asked to go through it\n- The user accepted a prior suggestion from the agent to run this\n  workflow\n\n**It is appropriate to *suggest* this skill** when the user's question\nis genuinely heavy enough to warrant it — a clean-slate new system, a\nmonolith-to-services extraction, or recurring \"every change touches\neverything\" pain that has resisted lighter analysis. Frame the\nsuggestion clearly: *\"There's a guided volatility-based decomposition\nworkflow (a few hours of back-and-forth, produces a written report).\nWant to run it, or would you rather just talk through this informally?\"*\n\nIf the user declines or wants something lighter, **don't run this\nskill**. Have the normal conversation instead. This workflow earns its\nweight on the right problems and drowns lighter ones.\n\nOnce the user opts in, proceed to *Starting a session* below.\n\n## Dependencies\n\nThe skill has one optional-but-recommended external dependency:\n\n- **[D2](https:\u002F\u002Fd2lang.com)** (CLI, free single binary) — used in\n  Phase 5 to render the final architecture and call-chain diagrams.\n  Without it, the skill falls back to embedded hand-written SVG, which\n  produces the same visual output but with more verbose source.\n  Install via `winget install terrastruct.d2` (Windows),\n  `brew install d2` (macOS), or download from \u003Chttps:\u002F\u002Fd2lang.com>.\n\nPhases 0–4 use only Mermaid (renders in any markdown viewer), so D2 is\nnot required to start a session — only to produce the final report's\npolished diagrams. The skill will check D2 availability when it reaches\nPhase 5 and tell the user once if it's missing, then continue with the\nSVG fallback.\n\n## The first principles (non-negotiable)\n\nThese four rules govern every decision in the session. Refer back to them\nconstantly.\n\n1. **Decompose by volatility, not functionality.** Every component must\n   answer: *what single axis of change does this encapsulate?* If the\n   answer is a verb or use-case step (Validate, Price, Ship, Notify), the\n   boundary is functional and wrong. If the answer is a crisp axis of\n   change (tax law, partner API, pricing rule, regulator), the boundary\n   is correct.\n\n2. **There is no feature.** Features are always and everywhere aspects\n   of *integration*, not implementation. The system supports a use case\n   by integrating components — never by housing the use case in a\n   component named after it. If the user asks \"where does feature X\n   live?\", the correct answer is always a call chain across components,\n   never a single component.\n\n3. **Never design against the requirements.** Requirements change.\n   Design against the smallest set of components that supports all\n   *core* use cases through different compositions. When requirements\n   change, the composition (Manager workflow code) changes — not the\n   decomposition.\n\n4. **Strive for the smallest set.** The architect's mission is the\n   smallest set of components that can compose to support every core use\n   case. Typical well-designed systems land at ~10–20 components total\n   (2–5 Managers, 2–3 Engines, 3–8 ResourceAccess + Resources, ~6\n   Utilities). A 1-component design is unvalidatable; a 100-component\n   design is functional decomposition.\n\n## How to run this interview\n\nThis skill is not a generator — it is a Socratic interview. The shape of\neach turn:\n\n- **Ask, then deepen.** When the user answers, follow up. \"What changes\n  when that changes?\" \"Why is that volatile?\" \"Has it actually changed,\n  or could it?\" Surface assumptions, contradictions, and what's missing.\n- **Reflect and paraphrase.** Restate what you heard before moving on.\n  This catches misinterpretation early and signals you're listening.\n- **Propose, don't only ask.** Use your domain knowledge to suggest\n  candidate volatilities the user didn't mention. *\"Most marketplaces of\n  this shape eventually see X — does that apply here?\"* This is the\n  primary unknown-unknowns surfacing move.\n- **Challenge candidates.** Every proposed volatility must answer: what\n  exactly is volatile, why is it volatile, what's the likelihood and\n  effect of change, and could it be a sub-attribute of something else?\n  Reject candidates that are merely variable or speculative.\n- **Ask with a structured choice at branches.** When the user faces a\n  discrete choice (new vs. refactor, encapsulate vs. fold-in, which Manager\n  owns X), present 2–4 options with brief reasoning rather than open prose\n  (Claude Code: `AskUserQuestion`; otherwise a numbered list).\n- **Stop and check in between phases.** Never proceed to the next phase\n  without an explicit \"looks good, continue\" from the user.\n\nThe user is the domain expert; you are the methodology expert. The job\nis to apply Löwy's rules to their context, not to teach iDesign as a\nlecture.\n\n## Starting a session\n\nBefore anything else, suggest a short kebab-case name for the system\nbeing decomposed. *\"I'm trying to figure out how to structure our order\npipeline\"* → suggest `order-pipeline`. Let the user override.\n\nThen ask, as a structured choice:\n\n> **Is this a new system or a refactor of an existing one?**\n>\n> - New system — greenfield, no legacy\n> - Refactor — existing system being restructured\n\nThe methodology is identical either way, but the final report differs\n(greenfield gets a build sequence; refactor gets a current-→-target\nmapping with extraction priorities).\n\nAll persistent artifacts live in `decompositions\u002F{system-name}\u002F`:\n\n| File                                          | Purpose                                            |\n|-----------------------------------------------|----------------------------------------------------|\n| `decompositions\u002F{system-name}\u002Freport.md`      | The growing recommendation report — the headline artifact |\n| `decompositions\u002F{system-name}\u002Fuse-cases.md`   | (Optional) raw use cases with swim lanes, if they grow long |\n\nWrite everything important to `report.md` as the session progresses.\nChat is the conversation surface; the file is the durable record.\n\nIf a decomposition was previously run on this system, pick\na distinct system name (`order-pipeline-v2`, `order-pipeline-rework`,\netc.) so the prior report isn't overwritten. The directory layout is\nintentional: each session gets its own `decompositions\u002F{system-name}\u002F`\nsubtree.\n\n---\n\n## Phase 0: Framing — Vision, Objectives, Mission\n\n**Goal**: Establish the business framing that *compels* volatility-based\ndecomposition. This phase exists because Löwy's hardest political problem\nis getting management to accept the methodology — and the trick is to\nhave the business itself instruct the architect to design correctly.\n\nWithout this framing, the rest of the session produces a defensible\ndesign that the org will still reject. With it, the design is the\nbusiness's logical conclusion.\n\n### Step 0a: The Vision\n\nAsk: **\"In one sentence, what is this system?\"**\n\nPush for terseness. *\"Read it like a legal statement.\"* A good vision is\none sentence, business-perspective, no implementation language.\n\n**Examples from the book:**\n- TradeMe: *\"A platform for building applications to support the TradeMe marketplace.\"*\n\nIf the user gives a paragraph, distill it together. If the user gives a\nfeature list, push back — features are not vision.\n\n### Step 0b: The Business Objectives\n\nAsk: **\"What does the business need from this system? Itemize.\"**\n\nRules:\n- Business perspective only. Reject technology objectives (\"use Kubernetes\"),\n  marketing objectives (\"look better than competitor X\"), and specific\n  requirements (\"send an email when …\").\n- Each objective must serve the vision. Reject anything that doesn't.\n- Aim for 3–8 objectives.\n\nIf the user lists fewer than three, probe: *\"What about scalability?\nLocalization? Compliance? Speed of feature delivery? Audit\ntrails? Recovery from incidents?\"* — propose candidates from common\nbusiness concerns.\n\n### Step 0c: The Mission Statement\n\nThis is the most important sentence in the whole session.\n\nDraft: **\"Design and build a collection of software components that the\ndevelopment team can assemble into applications and features.\"**\n\nAdjust the wording to the user's context, but preserve the structure:\nthe mission is to build **components** that **compose** into features —\nNOT to build the features themselves. This is the rhetorical move that\nmakes volatility-based decomposition the business's idea.\n\n### Step 0d: Write the framing\n\nAdd a `## Framing` section to `report.md` with the vision, the\nobjectives (as a numbered list), and the mission statement. End the\nsection with the chain:\n\n> Vision → Objectives → Mission Statement → Architecture\n\n**Stop and check in**:\n\n> \"Here's the framing. Does the mission statement actually capture how\n> you want the team to think about this system? Anything missing from\n> the objectives? Once you're happy, we'll move to use cases.\"\n\nWait for the user.\n\n---\n\n## Phase 1: Use Cases & Glossary\n\n**Goal**: Capture the required *behaviors* (not functionalities) of the\nsystem, identify the small number of **core use cases**, and build a\nshared glossary. This phase is where the user's mental model becomes\nvisible.\n\n### Step 1a: Gather raw use cases\n\nAsk: **\"Walk me through how the system will be used. Don't worry about\norder or completeness yet — just what needs to happen.\"**\n\nCapture each as a short list with: trigger, primary actor, sequence,\noutcome, error paths. Use plain text — diagrams come later if needed.\n\n**Surface unknown-unknowns aggressively here.** Löwy's quote: *\"the\nusers interact with or observe just a small part of the system, which\nrepresents the tip of the iceberg. The bulk of the system remains below\nthe waterline.\"* Probe for:\n- **Background processes** — schedulers, timers, batch jobs, reconciliations\n- **Admin \u002F operator use cases** — system administrators, support staff\n- **External-system-triggered use cases** — webhooks, partner callbacks\n- **Error and recovery paths** — refunds, reversals, retries, manual intervention\n- **Reporting and audit** — compliance, business intelligence, monitoring\n- **Long-running flows** — anything that spans multiple sessions \u002F devices \u002F days\n\nPropose candidates from your knowledge of similar systems. *\"In most\nmarketplace systems I've seen, there's also a dispute resolution flow.\nDoes that apply here?\"*\n\n### Step 1b: Swim lanes\n\nFor any use case involving multiple roles or subsystems, redraw it as an\nactivity diagram with **swim lanes** — one lane per role\u002Fentity (Client,\nMember, Market, Regulator, etc.). This isn't decoration; the swim lanes\nthemselves become candidate subsystem boundaries in Phase 3.\n\nIf the lanes are obvious from text, you can describe them; if not,\nsketch a Mermaid `flowchart` or just a structured outline.\n\n### Step 1c: The glossary (Four Questions)\n\nBuild a glossary by answering the **Four Questions**:\n\n| Question | What it captures |\n|----------|------------------|\n| **Who** | Actors — users, external systems, schedulers |\n| **What** | Top-level required behaviors \u002F capabilities |\n| **How** | Activities the system performs (the verbs) |\n| **Where** | Data and external dependencies — where state lives |\n\nThese map roughly to architectural layers later (Who→Clients,\nWhat→Managers, How→Engines + ResourceAccess, Where→Resources). The\n**What** list especially hints at subsystem boundaries.\n\n### Step 1d: Identify the core use cases\n\nThis is the most consequential step in Phase 1.\n\n> \"Most systems have 2–6 core use cases. The rest are variations.\n> Looking at what we've collected, which use cases capture the *essence\n> of the business*? If this system did nothing else, which would still\n> need to work?\"\n\nThe core use cases:\n- Are usually **abstractions** of the listed use cases — may need a new name\n- Are rarely explicit in any requirements doc\n- Tend to be 2–6; if the user names more than 6, push back: are these\n  really distinct, or variations?\n- Hint: count the bullets on a one-page marketing brochure for the system\n\n**Example from TradeMe**: of ~8 listed use cases (Add Tradesman, Request\nTradesman, Match, Assign, Terminate, Pay, Create Project, Close\nProject), only **Match Tradesman** is a core use case. The rest are\nplumbing.\n\n### Step 1e: Write Phase 1\n\nAdd to `report.md`:\n- `## Glossary` (Four Questions)\n- `## Use Cases` — list with brief sequences\n- `## Core Use Cases` — the 2–6, with a short paragraph each explaining\n  why this captures the essence\n\nIf use cases grow long, split them into `use-cases.md` and link.\n\n**Stop and check in**:\n\n> \"I've documented use cases and called out what I think are the core\n> ones. Read through and tell me: are the core use cases actually core?\n> Anything I've missed below the waterline? Once we agree on the cores,\n> we'll dig into volatility.\"\n\nWait for the user.\n\n---\n\n## Phase 2: Volatility Analysis\n\n**Goal**: Identify what's actually volatile (and what isn't), through\nchallenge and discovery rather than passive elicitation. This is the\nphase where unknown-unknowns are most likely to surface.\n\nThis phase produces a **Volatilities List** — candidate areas of change\nwith rationale. It does not yet name components.\n\n### Step 2a: The two axes of volatility\n\nLöwy defines exactly **two axes**:\n\n1. **Same customer over time** — even if the system perfectly fits one\n   customer today, that customer's context will change.\n2. **Different customers at the same point in time** — across the\n   customer base today, who uses the system differently?\n\nThe axes should be **independent**. If a candidate volatility can't be\ncleanly assigned to one axis or the other, that's a signal of\nfunctional decomposition in disguise — investigate further.\n\n> Note: you may have seen \"five axes\" frameworks (requirements \u002F\n> technology \u002F integration \u002F data \u002F policy) elsewhere. That isn't from\n> *Righting Software* — Löwy's book defines only the two axes above.\n> The five categories can be useful prompts during Step 2c (axes\n> sweep), but they aren't the framework.\n\n### Step 2b: Volatile vs. Variable\n\nBefore listing any volatility, share this distinction with the user:\n\n> **Variable**: something that changes but is handled in code with\n> conditional logic. Adding a new attribute to a customer record is\n> variable.\n>\n> **Volatile**: something open-ended whose changes ripple across the\n> system unless encapsulated. Swapping payment providers is volatile.\n\n**Only encapsulate volatility, not variability.** Most candidates the\nuser volunteers will be variability. Filter ruthlessly.\n\n### Step 2c: Surface candidates through multiple lenses\n\nDon't just ask \"what changes?\" — that gets opinions. Use these lenses\nto *discover* volatility the user hadn't named:\n\n1. **Change history**: *\"In the last 1–2 years, what changed in this\n   system or its predecessor, and why? Group changes by reason.\"*\n2. **Roadmap**: *\"What's planned for the next 6–12 months? What's been\n   discussed but not committed?\"*\n3. **The longevity heuristic** (powerful for surfacing missed\n   volatilities): *\"How long do you expect this system to be in\n   service? Now look back the same number of years — what changed in\n   that window? Whatever changed before will likely change again.\"*\n4. **Design for your competitors**: *\"Could your direct competitor use\n   this system as-is? Where would they need it to behave differently?\"*\n   Differences expose volatility; sameness exposes nature-of-business.\n5. **Solutions masquerading as requirements** (see Step 2d).\n6. **Anti-design contrast**: walk through a deliberately-bad\n   functional or domain decomposition; the points of pain it exposes\n   are often volatility you'd otherwise miss.\n7. **The agent proposes**: based on the domain (payments, marketplace,\n   logistics, SaaS, etc.), suggest 3–5 common volatilities for that\n   class of system the user hasn't mentioned. Present the candidates as\n   a structured choice if helpful.\n\n### Step 2d: Peel solutions-masquerading-as-requirements\n\nThis is Löwy's primary volatility-discovery technique. Many \"requirements\"\nthe user states are actually solutions to a deeper need. Peel them\nrecursively:\n\n> *\"Send an email confirmation.\"* → real requirement is **notify**\n> (could be email, SMS, push). Volatility: notification transport.\n>\n> *\"Cooking in the kitchen.\"* → real requirement is **feed the\n> occupants**. → real-real requirement is **occupants' well-being**.\n\nFor each candidate volatility, ask:\n1. Is this a solution or a real requirement?\n2. What other solutions could satisfy the same need?\n3. What's the *underlying* volatility?\n\n### Step 2e: Filter — what NOT to encapsulate\n\nVolatility-based decomposition can be over-applied. Reject candidates\nthat fail any of these tests:\n\n- **Nature of the business**: does it relate to what the company\n  fundamentally does? Two indicators: (a) change is rare,\n  (b) any attempt to encapsulate it would be done poorly given\n  available resources. *Don't encapsulate the nature of the business.*\n  (FedEx → Healthcare branch ≠ a volatility to encapsulate.)\n- **Speculative**: is the change extremely unlikely AND would the\n  encapsulation only be done poorly? Reject (the SCUBA-ready high\n  heels test).\n- **Merely variable**: handled by conditionals; no ripple effect.\n- **Out of scope**: the volatility is real, but it's owned by an\n  external Resource (e.g., an external payment system's internal\n  volatility).\n\nWhen rejecting a candidate, **state the rejection reason explicitly** in\nthe report. The user should be able to defend each rejection later.\n\n### Step 2f: Cluster and challenge\n\nFor each surviving candidate, document:\n- A name (just descriptive, not a component name yet)\n- What changes\n- Why (the underlying driver)\n- Which axis (or both)\n- Ripple radius — \"if this changes, what else has to change with it?\"\n\nActivities that change for the *same reason* belong together;\nactivities that change for *different reasons* belong apart, even if\nthey look related.\n\nThis list is the input to Phase 3, which is where components get\nnamed. A single component will often own several entries from this\nlist when they ripple together (e.g., a Manager owning the workflow\nvolatility of a whole use-case family), though a component owning one\nstandalone axis is also valid. Cluster axes here when they share a\nreason for change — that's exactly what this step is for — but don't\nassign component boundaries yet. Leave each clustered axis named so\nthe report's audit trail from volatilities to components stays\nintact, and let Phase 3 decide which clusters become which\ncomponents.\n\n### Step 2g: Write Phase 2\n\nAdd a `## Volatility Analysis` section to `report.md`:\n- Short paragraph per major volatility, with the why\n- Table of candidate volatility clusters\n- An **explicit list of rejected candidates** with rejection reasons\n\n```markdown\n### Rejected as not architecturally volatile\n\n| Candidate          | Reason                                                          |\n|--------------------|-----------------------------------------------------------------|\n| Adding new fields to a tradesman record | Variable, not volatile — handled by schema migration |\n| Branching into healthcare staffing      | Nature of the business — would redefine the company |\n| Optimization algorithms for project matching | Speculative — company isn't in the optimization business |\n```\n\n**Stop and check in**:\n\n> \"Here's the volatility analysis with the candidates I've accepted and\n> rejected. The rejections are as important as the accepts — challenge\n> any of them you disagree with. Anything I've split that should be\n> merged, merged that should be split, or missed entirely?\"\n\nWait for the user. Expect to iterate here.\n\nFor deeper coverage of volatility-discovery techniques, see\n`references\u002Fvolatility-techniques.md`.\n\n---\n\n## Phase 3: Component Definition\n\n**Goal**: Map the validated volatility list to the iDesign service\nhierarchy, using the Four Questions as a check.\n\n### Volatility-to-component mapping isn't 1:1\n\nA component can encapsulate one volatility or several. Both are valid;\nthe choice depends on whether the volatilities genuinely ripple\ntogether. *Righting Software* is explicit that many-to-one is common —\nthe TradeMe `MarketManager` owns three volatilities (managing projects,\nmatching tradesmen to projects, charging fees for the match) because\nthey're a family of logically related use cases sharing one\nworkflow-sequence axis. The same book also shows single-volatility\nManagers: TradeMe's `EducationManager` encapsulates only the education\nworkflow, with searching and regulatory compliance pushed to other\ncomponents.\n\nThere's a **directional bias toward consolidation**, driven by the\nsmallest-set principle (first principles #4). The book frames this as\nminimizing the amount of work in detailed design and implementation:\n1 component is too few (a monolith hides complexity inside) and 300\ncomponents is too many (integration cost explodes). The right answer\nlives around an order of magnitude of 10. The bias has a hard limit:\n**cohesion**. Volatilities that change for related reasons belong\ntogether; volatilities that change for unrelated reasons stay apart\neven when merging them would lower the count. Cramming unrelated axes\ninto one component isn't consolidation — it's functional decomposition\nwith a smaller N.\n\nCommon shapes (per *Righting Software*, Ch. 3 and Ch. 5):\n\n- A **Manager** often owns the sequence volatility of a *family* of\n  related use cases — frequently 2–4 listed volatilities sharing the\n  same workflow-orchestration axis. A Manager owning one volatility is\n  also valid when no other workflow family is related enough to share\n  orchestration with it (e.g., TradeMe's `EducationManager`).\n- An **Engine** has more restricted scope than a Manager, encapsulating\n  business rules and activities. Single-axis Engines are normal; the\n  book's `RegulationEngine` and `SearchEngine` are each one activity\n  volatility.\n- A **ResourceAccess** typically owns *both* the volatility of how the\n  Resource is accessed AND volatility of the Resource itself —\n  *\"Resource changes invariably change ResourceAccess as well\"* (Löwy).\n  Splitting these into separate components is a common\n  over-decomposition mistake.\n\nIf your Phase 2 list has 15 volatilities and your Phase 3 proposal has\n15 components, the design probably hasn't done any consolidation work —\nlook for related axes that could share a component. But don't force\nmerges; an N-to-N mapping that genuinely reflects N unrelated axes is\nbetter than a low count built on weak cohesion.\n\n### The hierarchy\n\n| Type             | Encapsulates                                              | Calls       |\n|------------------|-----------------------------------------------------------|-------------|\n| **Clients**      | Volatility in entry points (UIs, APIs, schedulers)        | Managers    |\n| **Managers**     | Volatility in the *sequence* \u002F workflow of use cases      | Engines, ResourceAccess, Utilities |\n| **Engines**      | Volatility in *activities* — business rules, calculations | ResourceAccess, Utilities |\n| **ResourceAccess** | Volatility in *how* a Resource is accessed AND in the Resource itself | Resources, Utilities |\n| **Resources**    | The actual data\u002Fexternal systems (DB, cache, external APIs) | —         |\n| **Utilities**    | Cross-cutting infrastructure (Logging, Security, Pub\u002FSub) | (anyone, via the utility bar) |\n\n### The Four Questions check\n\nMap each volatility to a question, and the question to a layer:\n\n| Question | Layer |\n|----------|-------|\n| **Who** interacts with the system? | Clients |\n| **What** is required of the system? | Managers |\n| **How** does the system perform business activities? | Engines |\n| **How** does the system access resources? | ResourceAccess |\n| **Where** does the system's state live? | Resources |\n\nIf a candidate component doesn't crisply answer one question, you've\neither picked the wrong layer or missed a volatility.\n\n### Closed architecture rules\n\nCalls go top-down only. Allowed:\n- Client → Manager\n- Manager → Engine\n- Manager → ResourceAccess (Engines are optional; Managers can call Access directly when there's no activity volatility to encapsulate)\n- Engine → ResourceAccess\n- Any layer → Utilities (the vertical bar)\n- ResourceAccess → Resources\n\nForbidden:\n- Sideways calls (Manager → Manager, Engine → Engine, ResourceAccess → ResourceAccess)\n- Calling up (Engine → Manager, Manager → Client)\n- Skip-level down (Manager → Resource, Client → Engine)\n- Clients calling multiple Managers in a single use case (sign of functional decomp)\n\nAllowed relaxations:\n- **Queued Manager → Manager** via a Pub\u002FSub or Message Bus utility (technically a downward call through Access; semantically a deferred second use case)\n- **Manager → Pub\u002FSub utility → other Managers** for fan-out (instead of sideways calls)\n\nSee `references\u002Fanti-patterns.md` for the full design-don'ts catalog.\n\n### Naming conventions\n\nTwo-part Pascal-case compound words. **Suffix = service type**:\n\n| Type             | Suffix         | Prefix                                              | Examples                                |\n|------------------|----------------|-----------------------------------------------------|-----------------------------------------|\n| Manager          | `Manager`      | Noun — the volatility encapsulated in the use cases | `MembershipManager`, `MarketManager`    |\n| Engine           | `Engine`       | Noun OR gerund — the encapsulated activity          | `SearchEngine`, `RegulationEngine`, `CalculatingEngine` |\n| ResourceAccess   | `Access`       | Noun — the Resource \u002F data                          | `MembersAccess`, `PaymentsAccess`, `WorkflowsAccess` |\n| Utility          | (varies)       | The cross-cutting concern                           | `Logger`, `Security`, `MessageBus`      |\n\n**Critical naming rules:**\n- The ResourceAccess suffix is `Access`, not `Accessor`. (Common\n  community mistake.)\n- **Gerunds belong only in Engines.** A gerund anywhere else\n  (`BillingManager`, `BillingAccess`) signals functional decomposition.\n- **Atomic business verbs never appear in prefixes.** Verbs like\n  `Credit`, `Debit`, `Pay` are operation names *on contracts*, not\n  service prefixes.\n- Avoid functional names: `OrderProcessor`, `PaymentHandler`,\n  `NotificationSender` are use-case names. Rename to the volatility\n  axis.\n\n### Forbidden vocabulary at this stage\n\nInfrastructure names don't belong in component names: Lambda, ECS, SQS,\nDynamoDB, S3, Kubernetes, Docker, Postgres, Redis. These are deployment\nconcerns. A `LambdaInvoker` is decomposed by infrastructure, not\nvolatility. Push back and propose a volatility-axis name.\n\n### Heuristics for getting the count right\n\n- **Manager : Engine ratio** — roughly 2:1. 1 Manager → 0–1 Engines.\n  2 Managers → ~1 Engine. 3 Managers → ~2 Engines. 5 Managers → ~3\n  Engines. **8+ Managers = failed design** (you've done functional\n  decomp).\n- **Per subsystem** — at most 3 Managers. Subsystems are vertical\n  slices (one Manager + its Engines + its ResourceAccess). Most\n  systems have only a handful of subsystems.\n- **Total components** — usually 10–20 in a well-designed system.\n- **Engines are uncommon.** For an Engine to exist there must be real\n  activity volatility — an unknown number of ways of doing something.\n  Lots of Engines almost always means functional decomp at the Engine\n  layer.\n\n### Utilities litmus test\n\nA component qualifies as a Utility only if it could plausibly serve any\nother system, even one as different as a *smart cappuccino machine*.\n- ✅ Logger, Security, Pub\u002FSub, Diagnostics — yes\n- ❌ MortgageInterestCalculator — no, it's domain logic in disguise\n\n### Almost-expendable Managers\n\nFor each Manager, apply the test: **how would you respond to a request\nto change this Manager?**\n\n- *Fight it \u002F fear the cost* → \"expensive\" Manager — too big, almost\n  certainly functional decomp inside\n- *Shrug it off, easy change* → \"expendable\" Manager — pass-through, no\n  real volatility encapsulated, design flaw\n- *Thoughtfully estimate how to adapt the workflow* → **\"almost\n  expendable\"** — correct. The Manager orchestrates Engines and Access,\n  encapsulating only sequence volatility, and absorbs change in its\n  workflow code without architectural impact.\n\nAim for almost-expendable Managers. Flag any that fail.\n\n### Write the components\n\nAdd a `## Components` section to `report.md`. Lead with a Mermaid\nlayered diagram, then one table per tier.\n\n#### Diagram template\n\nClient → Manager → Engine → ResourceAccess → Resource stacked\ntop-to-bottom, Utilities as a vertical bar on the right consumed from\nany layer. Arrows at the layer level only; the per-component\nrelationships are implied by layer membership.\n\n```mermaid\nblock-beta\n  columns 2\n\n  block:main:1\n    columns 1\n\n    block:client[\"CLIENT\"]\n      columns 4\n      %% Entry points — web, API, scheduler, inbound webhooks\n      %% Fill in actual components and apply: class id1,id2 client\n    end\n\n    block:managers[\"MANAGERS\"]\n      columns 3\n      %% Workflow orchestrators — one per major workflow family\n      %% Apply: class id1,id2 manager\n    end\n\n    block:engines[\"ENGINES\"]\n      columns 5\n      %% Business logic, rules, calculations\n      %% Apply: class id1,id2 engine\n    end\n\n    block:accessors[\"RESOURCE ACCESS\"]\n      columns 4\n      %% Wrap data + external integrations; expose atomic business verbs\n      %% Apply: class id1,id2 access\n    end\n\n    block:resources[\"RESOURCES\"]\n      columns 5\n      %% Databases, partner APIs, external systems\n      %% Apply: class id1,id2 resource\n    end\n  end\n\n  block:utilities[\"UTILITIES\"]:1\n    columns 1\n    %% Cross-cutting infrastructure, consumed from any layer\n    %% Apply: class id1,id2 utility\n  end\n\n  classDef client   fill:#d1fae5,stroke:#1f2937\n  classDef manager  fill:#fef9c3,stroke:#1f2937\n  classDef engine   fill:#fed7aa,stroke:#1f2937\n  classDef access   fill:#e5e7eb,stroke:#1f2937\n  classDef resource fill:#dbeafe,stroke:#1f2937\n  classDef utility  fill:#f3e8ff,stroke:#1f2937\n```\n\n**No arrows on the static diagram.** Layer membership already conveys\nthe call direction (Managers above Engines means Managers call into\nEngines). Per-component arrows would clutter without adding\ninformation. Save arrows for the call-chain diagrams in Phase 4, where\nthey show the specific path of one use case.\n\n**Layer colors are consistent across every diagram in the session**\n(Mermaid here, D2 and SVG in Phase 5): green for Client, yellow for\nManagers, orange for Engines, grey for Access, light blue for\nResources, lavender for Utilities. The same component always uses the\nsame color and stays in the same row\u002Fcolumn position across all\ndiagrams — that's what makes the Phase 4 symmetry check legible.\n\nPopulate every layer with at least one block before rendering — some\n`block-beta` renderers drop the layer label on empty layers.\n\nIf a single layer has more than ~7 components, the system probably\nwants a subsystem split.\n\n#### Component tables\n\nBeneath the diagram:\n\nList **every volatility cluster** a component owns in the `Encapsulates`\ncolumn — don't compress a multi-volatility component into a single\nphrase. The audit trail back to Phase 2 only works if each accepted\nvolatility shows up somewhere.\n\n```markdown\n### Managers\n| Component      | Encapsulates (volatility clusters)                                                    | Notes |\n|----------------|---------------------------------------------------------------------------------------|-------|\n| MarketManager  | Managing projects; matching tradesmen to projects; charging fees for the match | Three logically related use-case families share one orchestrator; only sequence volatility lives here |\n| MembershipManager | Membership management (add\u002Fremove, benefits, discounts); dispute resolution | Two related but distinct workflow families under one orchestrator |\n| EducationManager  | Education workflow                                                           | Single-volatility Manager; no other workflow family shares its orchestration axis |\n\n### Engines\n| Component        | Encapsulates                                | Depends on                |\n|------------------|---------------------------------------------|---------------------------|\n| RegulationEngine | Regulatory rule volatility across locales   | RegulationsAccess         |\n| SearchEngine     | Match-algorithm volatility                  | MembersAccess, ProjectsAccess |\n\n### ResourceAccess\n| Component        | Encapsulates                                                                  | Atomic business verbs    |\n|------------------|-------------------------------------------------------------------------------|--------------------------|\n| PaymentsAccess   | Payment provider choice; payment storage backend; reconciliation protocol     | Pay, Refund, Reconcile   |\n\n### Resources\n| Component | Notes |\n|-----------|-------|\n| Members   | Member profiles, history |\n\n### Utilities\n| Component   | Encapsulates                  |\n|-------------|-------------------------------|\n| Logger      | Logging framework volatility  |\n| MessageBus  | Pub\u002FSub transport volatility  |\n| Security    | Auth\u002FAuthZ volatility         |\n```\n\n**ResourceAccess contracts**: list the atomic business verbs each one\nexposes (e.g., `Pay`, `Credit`, `Debit`, `Match`, `Reserve`). Do **not**\nlist CRUD\u002FIO operations (`Insert`, `Select`, `Read`, `Write`,\n`Open`) — those leak the Resource technology.\n\n**Stop and check in**:\n\n> \"Here's the component proposal. For each Manager, do the\n> almost-expendable test in your head: how do you feel about being\n> asked to change it? Walk through which names feel off, which\n> boundaries feel wrong, or where I've put something at the wrong\n> tier.\"\n\nWait for the user.\n\n---\n\n## Phase 4: Validation via Call Chains\n\n**Goal**: Prove the design is composable by producing one **call chain\ndiagram** per core use case, then checking for symmetry and\ncomposability across them.\n\nA decomposition that doesn't survive its own validation isn't\nvolatility-based — it's guesses with better names.\n\n### What a call chain is\n\nFor each core use case, draw the interaction:\n- Components appear in their layer positions (same layout as the static\n  diagram)\n- **Solid black arrows** = synchronous calls\n- **Dashed gray arrows** = queued \u002F asynchronous calls\n- The call chain *superimposes* on the layered diagram — don't redraw,\n  just highlight\n\nUse Mermaid `flowchart` here. Mermaid is the **iteration format** — it\nrenders inline in markdown, costs nothing to regenerate as the design\nshifts, and is good enough for the symmetry\u002Fcomposability checks in this\nphase. Final-report rendering switches to D2 or SVG in Phase 5; don't\nspend effort polishing diagrams here. Example:\n\n```mermaid\nflowchart TD\n  Client[Tradesman Portal]:::client\n  Bus[MessageBus]:::utility\n  Mgr[MembershipManager]:::manager\n  Eng[RegulationEngine]:::engine\n  AccM[MembersAccess]:::access\n  AccP[PaymentsAccess]:::access\n  Members[(Members)]:::resource\n  Payments[(Payments)]:::resource\n\n  Client -. queued .-> Bus\n  Bus --> Mgr\n  Mgr --> Eng\n  Mgr --> AccM\n  Mgr --> AccP\n  AccM --> Members\n  AccP --> Payments\n\n  classDef client   fill:#d1fae5,stroke:#1f2937\n  classDef manager  fill:#fef9c3,stroke:#1f2937\n  classDef engine   fill:#fed7aa,stroke:#1f2937\n  classDef access   fill:#e5e7eb,stroke:#1f2937\n  classDef resource fill:#dbeafe,stroke:#1f2937\n  classDef utility  fill:#f3e8ff,stroke:#1f2937\n```\n\nAdd a brief narrative under each diagram: which Manager owns the\nworkflow, what triggers it, what completes it.\n\n### Step 4a: Draw one chain per core use case\n\nProduce a call chain for **every core use case** identified in Phase 1.\nDon't validate non-core use cases here — those are variations, and the\ncore chains should compose to cover them.\n\n### Step 4b: Symmetry check\n\nLay the chains side by side and look for **structural similarity**.\n- Do all chains follow the same shape (Client → Bus → Manager → Engine → Access → Resource)?\n- Does every workflow end with a Pub\u002FSub publish, OR none of them do?\n- Are queued vs. synchronous call patterns consistent across use cases?\n\n**Asymmetry is a design smell.** If three core use cases publish an\nevent at the end and the fourth doesn't, ask: why is the fourth\ndifferent? What's missing or extra?\n\nLöwy's words: *\"Symmetry is so fundamental for good design that you\nshould generally see the same call patterns across Managers.\"*\n\n### Step 4c: Composability proof\n\nGenerate a **new hypothetical use case** — something the user didn't\nmention but could plausibly want — and demonstrate that the existing\ncomponents compose to support it without architectural change.\n\n> *\"What if you needed to add 'analyze projects from 2022–2024 for\n> profitability'? Walk me through the call chain using only the\n> components we already have.\"*\n\nIf this fails — if the new use case requires a new Manager or a layer\nviolation — the decomposition isn't composable enough, and you should\nreturn to Phase 2.\n\n### Step 4d: Ripple-radius check\n\nFor 3–5 plausible future changes (drawn from the roadmap, change\nhistory, and competitor framing in Phase 2), document which components\neach change would touch.\n\n- **Good**: each scenario touches 1–2 components\n- **Bad**: any scenario touches 3+ components → unencapsulated\n  volatility; revisit Phase 2\n\nWhen a scenario fails, don't paper over it. Tell the user:\n\n> \"This scenario blows past three components. That means we have an\n> axis of change that isn't encapsulated yet. Let me re-examine the\n> clusters.\"\n\nThen loop back to Phase 2.\n\n### Write Phase 4\n\nAdd a `## Validation` section to `report.md` containing:\n- One subsection per core use case, with the Mermaid call chain and a\n  short narrative\n- A \"Symmetry observations\" subsection\n- A \"Composability check\" subsection with the hypothetical\n- A \"Ripple-radius scenarios\" subsection (each scenario + components touched + ✅\u002F❌)\n\n**Stop and check in** once chains and scenarios all pass:\n\n> \"All call chains hold and the ripple-radius scenarios stay contained.\n> Ready to write the final recommendation, or do you want to add more\n> stress-test scenarios first?\"\n\n---\n\n## Phase 5: Recommendation Report\n\n**Goal**: Finalize `report.md` as a usable, handoff-ready artifact.\n\nThe framing, glossary, use cases, volatility analysis, components, and\nvalidation are already in the file from Phases 0–4. This phase adds:\n\n### Implementation sequence (new systems)\n\nFor greenfield, give a bottom-up build order:\n\n1. **Utilities first** — foundations, depend on nothing\n2. **Resources** — provisioned alongside Utilities\n3. **ResourceAccess** — depends only on Utilities and Resources\n4. **Engines** — depends on Access + Utilities\n5. **Managers** — orchestrate everything\n\nCall out which components need senior attention — typically the most\nvolatile ones, whose interfaces are the contract that must absorb\nfuture change.\n\n### Migration plan (refactors)\n\nFor existing systems, add a `## Current → Target` mapping:\n\n- For each target component, identify where the logic currently lives\n- Flag extraction priorities (which boundary hurts most today?)\n- Note coupling that must break first (shared databases, peer calls,\n  skip-level calls)\n- Recommend an extraction order that minimizes intermediate breakage\n- If the existing system has infrastructure-named components\n  (`LambdaInvoker`, `SQSQueueProcessor`, `RedisCache`), propose\n  volatility-axis renames as part of the mapping\n\n### Optional: Operational concepts\n\nIf the system warrants advanced run-time patterns (Message Bus,\nWorkflow Managers, Message-Is-The-Application), add an `## Operational\nConcepts` section. **These are optional and require organizational\nmaturity** — see `references\u002Foperational-concepts.md` for guidance on\nwhen to recommend them and when to leave them out.\n\nDefault position: do **not** recommend these unless the user's\nobjectives in Phase 0 specifically demand them (e.g., \"quick turnaround\nfor new features\", \"support deep customization across markets\",\n\"forward-looking integration\"). Otherwise, leave the run-time\ninteractions as direct synchronous calls and let the team mature into\nthe more elaborate patterns later.\n\n### Render polished diagrams\n\nBefore finalizing the report, regenerate the static architecture and\neach call chain in a higher-fidelity format. Mermaid is fine during\niteration but doesn't preserve component positions across diagrams,\nwhich makes the Phase 4 symmetry check hard to read visually.\n\n**Step A: Check `d2` availability**\n\n```bash\nd2 --version\n```\n\nIf the command succeeds, proceed to Step B. If it fails with\n\"command not found\", continue to Step C.\n\nIf you're on Windows and the user told you they just installed D2 but\nthe command isn't found, suggest restarting the shell to pick up the\nnew PATH before falling back.\n\n**Step B: Generate D2 source and render**\n\nWrite D2 source under `decompositions\u002F{system-name}\u002Fdiagrams\u002F`:\n- One `static.d2` for the layered architecture\n- One `callchain-{usecase-slug}.d2` per core use case (use the same\n  filename slug for every diagram referencing the use case)\n\nUse the canonical templates in `references\u002Fdiagram-templates.md`. The\ntemplates enforce a **stable component coordinate map** — the same\ncomponent always sits in the same row\u002Fcolumn across every diagram,\nwhich is what makes Phase 4's symmetry check easy to verify by eye.\n\nRender each:\n\n```bash\nd2 diagrams\u002Fstatic.d2 diagrams\u002Fstatic.svg\nd2 diagrams\u002Fcallchain-match-tradesman.d2 diagrams\u002Fcallchain-match-tradesman.svg\n```\n\nThen reference the rendered SVGs from `report.md` with relative paths:\n\n```markdown\n![Static architecture](diagrams\u002Fstatic.svg)\n![Match Tradesman call chain](diagrams\u002Fcallchain-match-tradesman.svg)\n```\n\n**Step C: `d2` not installed — pause or fall back**\n\nD2 is the preferred final format because it's **codified source that\ncan be modified after the fact**. The SVG fallback produces the same\nvisual output but is awkward to edit later (hand-tweaking SVG paths\nvs. editing readable D2 source).\n\nOffer two paths as a structured choice:\n\n> `d2` isn't on PATH, so the final diagrams can't be emitted in their\n> preferred (editable) form. Two options:\n>\n> 1. **Pause and install** — `winget install terrastruct.d2` (Windows)\n>    or `brew install d2` (macOS), then restart the shell and tell me\n>    to continue. This is the recommended path; D2 output is editable\n>    going forward.\n> 2. **Fall back to embedded SVG** — visually identical, but harder\n>    to modify after the report is written. Pick this only if D2\n>    install is genuinely not an option.\n\nIf the user picks option 1, stop and wait. When they resume, retry\nStep A.\n\nIf the user picks option 2, write SVG directly to `diagrams\u002F` using\nthe SVG templates in `references\u002Fdiagram-templates.md` (same\ncoordinate map, just emitted as SVG).\n\n**Don't mix formats in the final report.** Pick one and use it for\nthe static diagram and every call chain. Consistency is the point.\n\n### Open questions and risks\n\nSurface anything you couldn't resolve:\n- Volatility axes where evidence was thin\n- Components that passed validation but felt fragile\n- Assumptions that should be re-tested in 6 months\n- Areas where the user disagreed with the methodology — note the\n  disagreement, the user's reasoning, and the implication\n\n### Hand off\n\nTell the user:\n\n> \"`decompositions\u002F{system-name}\u002Freport.md` is the recommendation\n> (with raw use cases in `use-cases.md` if that file exists). It's\n> structured so you can hand it to a team to either build from or\n> refactor toward. Want me to draft an ADR or a kickoff doc from it,\n> or are we done?\"\n\n---\n\n## Reference: when to consult the extra material\n\nThis skill is mostly self-contained, but four reference files cover\ndeeper material that doesn't belong inline:\n\n- **`references\u002Fvolatility-techniques.md`** — extended techniques for\n  surfacing volatility (the anti-design effort, design factoring\n  iterations, design-for-your-competitors variants). Consult during\n  Phase 2 if the user is stuck or the candidate list feels thin.\n- **`references\u002Foperational-concepts.md`** — Message Bus,\n  Message-Is-The-Application pattern, Workflow Managers. Consult in\n  Phase 5 only if the Phase 0 objectives suggest advanced patterns are\n  warranted.\n- **`references\u002Fanti-patterns.md`** — full catalog of design \"don'ts\"\n  from the book (event publishing rules, queue rules, layer-call\n  rules). Consult during Phase 3 component definition and during Phase\n  4 validation as a checklist.\n- **`references\u002Fdiagram-templates.md`** — canonical component\n  coordinate map and source templates for both D2 and SVG output.\n  Consult in Phase 5 when rendering the final diagrams.\n\n---\n\n## Things not to do\n\n- **Don't lecture.** The user knows their domain; you know the\n  methodology. Apply the rules to their context.\n- **Don't skip Phase 0.** Skipping framing produces a defensible\n  design that the org will reject anyway.\n- **Don't analyze during Phase 1.** Use-case walkthroughs lose\n  information the moment you start proposing boundaries.\n- **Don't accept volatility candidates passively.** Challenge each\n  one with the volatile-vs-variable, solutions-masquerading,\n  nature-of-business, and longevity tests. The user proposed it doesn't\n  mean it survives.\n- **Don't skip validation.** Call chains are not optional decoration —\n  they are the proof that the decomposition is composable.\n- **Don't recommend operational concepts (Message Bus, MITA, Workflow\n  Managers) by default.** They require organizational maturity. Match\n  the recommendation to the Phase 0 objectives and the team's stated\n  capabilities.\n- **Don't let infrastructure names into component names.** Save those\n  for the deployment plan.\n- **Don't treat this skill as a one-shot generator.** The value is in\n  the back-and-forth — the user's reactions in Phases 2–4 are where the\n  decomposition actually gets right.\n- **Don't widen scope into deployment, technology choices, or org\n  structure.** Those come *after* the decomposition exists.\n- **Don't blend rejected and accepted volatility silently.** Reject\n  candidates explicitly with a stated reason in the report.\n- **Don't accept the user's first answer as final.** Use the\n  unknown-unknowns surfacing techniques (competitor framing, longevity\n  heuristic, candidate proposals from your domain knowledge) to push\n  past what the user already knew to say.\n",{"name":5,"description":7},"main","029bf6d49f3d270442ace55a01cccb40113f7efa","plugins\u002Feng\u002Fskills\u002Frighting-software-system-design","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills","https:\u002F\u002Fgithub.com\u002Fesond","https:\u002F\u002Flinktr.ee\u002Fesond0","Serial pragmatist.\r\n\r\nCheck out my other repos at @hexagram-solutions! ","2026-11-07 00:00:12",{"source":8,"skillName":5,"commands":66,"prompt":76,"zipAvailable":77},[67,70,73],{"tool":68,"command":69},"npx","npx skills add esond\u002Fskills --skill righting-software-system-design",{"tool":71,"command":72},"bunx","bunx skills add esond\u002Fskills --skill righting-software-system-design",{"tool":74,"command":75},"pnpm","pnpm dlx skills add esond\u002Fskills --skill righting-software-system-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002FSKILL.md",true,[79,85,89,93,97],{"path":80,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":83,"sourceHtmlUrl":84},"agents\u002Fopenai.yaml","REFERENCE","参考文档",147,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002Fagents\u002Fopenai.yaml",{"path":86,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Fanti-patterns.md",13499,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002Freferences\u002Fanti-patterns.md",{"path":90,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":91,"sourceHtmlUrl":92},"references\u002Fdiagram-templates.md",16940,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002Freferences\u002Fdiagram-templates.md",{"path":94,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":95,"sourceHtmlUrl":96},"references\u002Foperational-concepts.md",8038,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002Freferences\u002Foperational-concepts.md",{"path":98,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":99,"sourceHtmlUrl":100},"references\u002Fvolatility-techniques.md",8880,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002Freferences\u002Fvolatility-techniques.md",[102,129,154,179,191,211],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":52},"01M71FF0KCP66CRNT9AT1T18Z9","work-item-voice","Write or edit the user's issues in their own voice, in any work tracker — Jira, Linear, GitHub Issues, Azure DevOps. Covers features (new behavior), tasks (work that needs doing), and bugs (behavior that does not match expectation). Load this whenever the deliverable is an issue body, whether they say \"file a bug\", \"write a ticket\", \"draft a story\", \"create an issue for this\", \"turn this into a Jira\", \"write this up in Linear\", or paste a thread and ask for an issue out of it. Load it too whenever text goes into an issue that already exists — \"record this in the issue\", \"add what we found to the ticket\", \"note this on the card\", \"update the one about refunds\", or naming an issue by its key and asking for a fact to go in it — and when writing or updating one is a step inside a larger task. Features get behavior-driven framing with no implementation prescribed, and bugs get expected versus actual. Not for a comment on an issue, which is a conversation turn.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fesond\u002Fskills\u002Fwork-item-voice\u002FSKILL.md",[],[109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128],"work","work item voice","work item","voice","conversation","which","get","card","ticket","up","issues","new","writing","azure devops","when","ask","tasks","text","create","tracker",{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":138,"publishedAt":52},"01M71FETV1H7JPCTSKMW3XZV1T","conversational-voice","Write the user's side of a conversation with another person, in the user's own voice: Slack messages and replies, DMs, email, PR and code-review comments, Linear or Jira comments, and any other turn in an exchange that goes out under the user's name. Load this whenever the deliverable is a message a human will read as written by the user, whether they say \"draft a Slack message\", \"reply to this\", \"how should I word this\", \"tell the team\", \"ask them about X\", \"send a note to\", or just paste a thread and ask what to say back. Load it too when tightening, shortening, or sanity-checking a message they already wrote, and when a message is one step of a larger task. The register is direct and informal, the way they'd talk to a friend or acquaintance, with the answer up front for a reader who skims. Not for something the user authors rather than sends — an issue body, a PR description, a commit message — even though a person reads those too.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fesond\u002Fskills\u002Fconversational-voice\u002FSKILL.md",[135],{"categoryNo":136,"categoryName":137,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000005","邮件与沟通",[139,112,140,113,141,142,118,143,123,124,144,145,146,147,148,149,150,151,152,153],"conversational voice","back","messages","send","slack messages","code","commit","team","code-review","review","sanity","message","slack","human","how",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":163,"publishedAt":52},"01M71FEN36NS9Y4RVX6KQ704TB","sync-core-repo-docs","Create or audit a repo's three core doc files — README.md, the agent instructions file (AGENTS.md or CLAUDE.md), and REVIEW.md — in that dependency order. If a file is missing, generate it from the codebase; if it exists, audit it against the current code and apply targeted fixes after confirmation. README.md gets a developer from clone to running the project; AGENTS.md captures coding guidance for the agent (delegating to \u002Finit or claude-md-improver); REVIEW.md holds guidance for code reviewers, human or automated, without duplicating AGENTS.md. Target files with --readme, --claude, and --review, or run all three. Use whenever the user wants to set up, bootstrap, scaffold, refresh, audit, update, or sync a repo's docs, or says things like \"create a README\", \"is my README still accurate\", \"write a CLAUDE.md\", \"write an AGENTS.md\", \"audit our docs\", or \"get this repo ready for contributors\" — even when only one file is named. Prefer it over claude-md-improver when README or REVIEW are also in scope.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Fsync-core-repo-docs\u002FSKILL.md",[160],{"categoryNo":161,"categoryName":162,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师",[164,165,166,167,168,169,170,171,172,115,173,174,118,175,176,177,178,123,144,148],"sync","sync core repo docs","repo docs","core","repo","docs","agent instructions","SET","ready","scope","project","init","only","files","confirmation",{"skillNo":180,"name":181,"nameZh":6,"description":182,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":183,"categories":184,"keywords":185,"publishedAt":52},"01M71FEKJQ2G2NQ4NCXRR9SD63","sync-core-docs","Create or audit a repo's README.md, AGENTS.md\u002FCLAUDE.md, and REVIEW.md docs.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Fsync-core-docs\u002FSKILL.md",[],[186,169,167,164,127,187,188,189,190,168,148],"sync core docs","true","md docs","audit","README",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":197,"publishedAt":52},"01M71FE4QYB436ZS8H3SWWHA4F","reorganize-branch-commits","Reorganize the commits on a non-default git branch into a clean, logical history by rewriting the branch — `git reset` + re-commit by default, `git rebase -i` when commit boundaries already align. Propose groupings based on the actual work done (features, refactors, tests, fixes, docs), get explicit user approval, back the branch up, then rewrite history. Use this skill whenever the user wants to tidy up, clean up, reorganize, restructure, squash, or curate commits on a feature branch — even if they phrase it as \"my branch is a mess\", \"squash this down\", \"combine these commits\", \"fix up the commit log before I open a PR\", or \"make the commits presentable for review\". Trigger proactively when the user is about to open or push a PR and the branch has scrappy\u002FWIP\u002F\"fix\" commits to collapse. Refuses to operate on default or release-shaped branches (main, master, develop, trunk, production, release, or the repo default) — a feature-branch-only tool.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Freorganize-branch-commits\u002FSKILL.md",[],[198,199,200,140,201,115,202,203,204,118,205,206,207,208,176,209,57,123,210,145],"branch","reorganize branch commits","commits","operate","align","re","default","fix","clean","branches","open","tidy","done",{"skillNo":212,"name":213,"nameZh":6,"description":214,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":215,"categories":216,"keywords":217,"publishedAt":52},"01M71FE0TZQXH44K88DSFDEA98","pr-review-resolver","Address outstanding review feedback on a GitHub pull request: unresolved review threads, submitted review bodies, and general PR comments. Triages each critically, fixes what it agrees with, and pushes back on the rest. Use whenever the user wants to address, fix, resolve, or work through PR review comments or feedback, even if they just say \"handle the PR comments\", \"fix what the reviewers said\", or \"go through the PR\", or pastes a PR URL and asks you to act on the feedback there.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Fpr-review-resolver\u002FSKILL.md",[],[218,219,148,220,221,140,222,223,224,225,226,205,227,228,229,230,231,232,124,233],"pr","pr review","resolver","pr review resolver","pull","feedback","pr review comments","fixes","just","general","review feedback","use","number","URL","you","comments"]