diff --git a/.claude/skills/grill-with-docs/ADR-FORMAT.md b/.claude/skills/domain-modeling/ADR-FORMAT.md similarity index 100% rename from .claude/skills/grill-with-docs/ADR-FORMAT.md rename to .claude/skills/domain-modeling/ADR-FORMAT.md diff --git a/.claude/skills/grill-with-docs/CONTEXT-FORMAT.md b/.claude/skills/domain-modeling/CONTEXT-FORMAT.md similarity index 100% rename from .claude/skills/grill-with-docs/CONTEXT-FORMAT.md rename to .claude/skills/domain-modeling/CONTEXT-FORMAT.md diff --git a/.claude/skills/domain-modeling/SKILL.md b/.claude/skills/domain-modeling/SKILL.md new file mode 100644 index 00000000..d0f7e1a5 --- /dev/null +++ b/.claude/skills/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. +--- + +# Domain Modeling + +Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) + +## File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.claude/skills/grill-with-docs/SKILL.md index 5ea0aa91..bed05d2b 100644 --- a/.claude/skills/grill-with-docs/SKILL.md +++ b/.claude/skills/grill-with-docs/SKILL.md @@ -1,88 +1,7 @@ --- name: grill-with-docs -description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. +disable-model-invocation: true --- - - -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time, waiting for feedback on each question before continuing. - -If a question can be answered by exploring the codebase, explore the codebase instead. - - - - - -## Domain awareness - -During codebase exploration, also look for existing documentation: - -### File structure - -Most repos have a single context: - -``` -/ -├── CONTEXT.md -├── docs/ -│ └── adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: - -``` -/ -├── CONTEXT-MAP.md -├── docs/ -│ └── adr/ ← system-wide decisions -├── src/ -│ ├── ordering/ -│ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions -│ └── billing/ -│ ├── CONTEXT.md -│ └── docs/adr/ -``` - -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. - -## During the session - -### Challenge against the glossary - -When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" - -### Sharpen fuzzy language - -When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." - -### Discuss concrete scenarios - -When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. - -### Cross-reference with code - -When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" - -### Update CONTEXT.md inline - -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). - -`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. - -### Offer ADRs sparingly - -Only offer to create an ADR when all three are true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will wonder "why did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). - - +Run a `/grilling` session, using the `/domain-modeling` skill. diff --git a/.claude/skills/grilling/SKILL.md b/.claude/skills/grilling/SKILL.md new file mode 100644 index 00000000..219930f7 --- /dev/null +++ b/.claude/skills/grilling/SKILL.md @@ -0,0 +1,12 @@ +--- +name: grilling +description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases. +--- + +Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. + +If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. + +Do not enact the plan until I confirm we have reached a shared understanding. diff --git a/.claude/skills/improve-codebase-architecture/SKILL.md b/.claude/skills/improve-codebase-architecture/SKILL.md index 05984a60..b41ffef6 100644 --- a/.claude/skills/improve-codebase-architecture/SKILL.md +++ b/.claude/skills/improve-codebase-architecture/SKILL.md @@ -65,7 +65,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des Side effects happen inline as decisions crystallize: -- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/domain-modeling` (see [CONTEXT-FORMAT.md](../domain-modeling/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../domain-modeling/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). diff --git a/CLAUDE.md b/CLAUDE.md index 79670a86..13be793a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ Frontend and backend conventions live alongside their code and auto-load when ed ## Agent skills -Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-spec → to-tickets → triage`. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md` and `docs/adr/0003-misc-rename-to-spec-to-tickets.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above. +Workflow skills (commit, open-pr, update-pr, address-pr-comments, run-local, verify-telemetry, verify-graph) and Matt Pocock's engineering and issue-authoring skills live in `.claude/skills/`. The AI issue-authoring flow is `grill-with-docs → to-spec → to-tickets → triage`. `grill-with-docs` orchestrates the `grilling` and `domain-modeling` primitives. See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`, `docs/adr/0003-misc-rename-to-spec-to-tickets.md`, and `docs/adr/0004-misc-split-grill-with-docs.md`. The `caveman` terse mode is on by default in this repo as a pilot — see the Communication section above. ### Issue tracker diff --git a/docs/adr/0004-misc-split-grill-with-docs.md b/docs/adr/0004-misc-split-grill-with-docs.md new file mode 100644 index 00000000..47522d1d --- /dev/null +++ b/docs/adr/0004-misc-split-grill-with-docs.md @@ -0,0 +1,26 @@ +# Split grill-with-docs into grilling + domain-modeling primitives + +Argos decomposes the monolithic `grill-with-docs` skill into two reusable primitives, tracking Matt Pocock's upstream split. `grill-with-docs` becomes a thin orchestrator — "Run a `/grilling` session, using the `/domain-modeling` skill" — and its two halves move into standalone skills: + +- **`grilling`** — the relentless interview primitive (walk the design tree, one question at a time, recommend an answer for each). +- **`domain-modeling`** — the active doc discipline (challenge terms against `CONTEXT.md`, sharpen fuzzy language, offer ADRs sparingly), carrying the `CONTEXT-FORMAT.md` and `ADR-FORMAT.md` bundled files. + +## Considered Options + +- Leave the monolith as-is. +- Patch the monolith in place (port the fixes without splitting). +- Adopt the upstream split (chosen). + +## Why split + +- The two halves are independently reusable. `improve-codebase-architecture` already leans on both the grilling conversation and the `CONTEXT.md` / ADR discipline; other skills can now invoke `grilling` or `domain-modeling` directly instead of duplicating the prose. +- The split let us fix a real regression the monolith carried. Our `grill-with-docs` still had the blanket line "if a question can be answered by exploring the codebase, explore the codebase instead" — the exact wording that lets a grilling agent answer its own **decisions** and race ahead. The new `grilling` splits **facts** (look them up) from **decisions** (put each to the human and wait), and adds a confirmation gate: do not enact the plan until the user confirms shared understanding. +- `disable-model-invocation: true` moves onto `grill-with-docs` (a user-invoked flow entry); `grilling` and `domain-modeling` stay model-invocable so the agent and other skills can reach them. + +## Consequences + +- New skills `.claude/skills/grilling/` and `.claude/skills/domain-modeling/`; `grill-with-docs/SKILL.md` shrinks to the orchestrator line. +- `CONTEXT-FORMAT.md` and `ADR-FORMAT.md` move from `grill-with-docs/` to `domain-modeling/`. The two links in `improve-codebase-architecture/SKILL.md` are repointed to `../domain-modeling/`, and its "same discipline as `/grill-with-docs`" note now points at `/domain-modeling`. +- The `grill-with-docs → to-spec → to-tickets → triage` flow named in `CLAUDE.md` and ADR-0002/0003 is unchanged — `grill-with-docs` still exists as the entry point, it just delegates. + +See `docs/adr/0002-misc-adopt-matt-pocock-skills.md`, `docs/adr/0003-misc-rename-to-spec-to-tickets.md`.