Files

T

Gabriel Brown 89761a7da3 Keep the personal half of the desktop in one place, and ask before installing it

Agent instructions, skills, SSH host aliases and expansion triggers are worth
having identical on every machine one person owns, and belong in none of the
shared configuration. They live in user/ now, with a manifest saying where each
piece goes and a link-user stage that puts it there.

That stage does nothing unless the machine said yes. Somebody who clones Panama
to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was;
the question names the destinations and defaults to no. Anything displaced goes
to config/old rather than being deleted.

~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one
file, which is the drift this exists to prevent.

Also adds the vitals toggles for the battery and Claude usage readouts, which
had preferences and no way to reach them.

2026-08-22 08:54:43 -04:00

8.4 KiB

Raw Permalink Blame History

name, description

name	description
grilling	Use before any creative work, meaning a new feature, component, or change in behaviour, and whenever a plan, design, or decision needs stress-testing before code exists. Triggers on "grill me", "think this through", and on any request to build something not yet designed.

Grilling

Interview the user relentlessly until you reach a shared understanding, then stop. The output is an agreed design, never code.

Write no code, scaffold nothing, invoke no implementation skill, and change no file until you have stated what you intend to do and the user has said yes. The **ceremony** scales with the task. The **gate** never does.

Classify the path first

Say the classification out loud before the first question, so it can be overridden:

"This looks bounded, so I'll ask a couple of questions and present a short design here rather than write anything up."

Path	What it is	Output
Spike	A feasibility question: "can we", "is it possible", "quick and dirty is fine"	An answer, not code you keep. Present the question and probe in 2-3 sentences, get a nod, find out as cheaply as correctness allows. Anything built stays labelled throwaway.
Bounded	A well-scoped change to a flow that already exists in this repo: a flag, a small endpoint, a one-file fix	A short design in chat, then stop. No document.
Architectural	New projects, new subsystems, changes that restructure how things fit together or alter an interface others depend on	Full rounds, approaches, a sectioned design, and a written spec.

Bounded measures the repo, not your familiarity. Knowing the kind of app is not enough: if the flow being changed is not already there to read, the task is not bounded.

The ratchet is one-way. In doubt between two paths, take the heavier one. Hidden complexity found mid-task upgrades the path: stop, say so, step up. Nothing ever downgrades mid-task.

The interview

Model the problem as a design tree: every decision branches into the decisions hanging off it. The frontier is every decision whose prerequisites are already settled, meaning the questions you can ask now without guessing at answers you have not heard yet.

Work the tree in rounds. Ask the whole frontier in one round, numbered, each carrying your recommended answer. Then wait.

❓ **Q1** - **<question title>**: <question body, which may run to several paragraphs and offer
multiple choices>

➡️ <your recommended answer>

---

❓ **Q2** - **<question title>**: <body>

➡️ <your recommended answer>

Each round's answers reshape the tree: settled decisions push the frontier outward and unblock what depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a later round, not this one.

Where a round is four questions or fewer and every answer is a discrete choice, ask it through AskUserQuestion instead, one option list per question, your recommendation first and marked. The markdown format above is the default, because it scales past four and carries reasoning the tool's option labels cannot.

The session is done when the frontier is empty: every branch visited, nothing left silently assumed.

Facts are yours, decisions are theirs

Finding facts is your job, never the user's. When a frontier question needs a fact from the environment (what a file contains, whether a package is installed, how an endpoint currently behaves), dispatch a subagent and find out. Never ask the user something you could look up.

Do not block on it. A running exploration is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now.

The decisions are the user's. Put each one to them and wait.

Per-path checklists

Announce the path, then create a todo per item and work them in order.

Spike

Explore enough project context to frame the probe
Present the question and probe plan, 2-3 sentences
Get approval, a nod is enough
Investigate as cheaply as correctness allows
Report a recommendation, labelling anything built as throwaway

Bounded

Explore project context: files, docs, recent commits
Run one round of the frontier, usually a short one
Present a short design in chat: approach, files touched, testing
Stop and wait for an explicit yes. Presenting the design and starting in the same breath is skipping the gate
Implement through the normal workflow. No plan document

Architectural

Explore project context: files, docs, recent commits
Work the frontier in rounds until it is empty
Propose 2-3 approaches with trade-offs, leading with your recommendation and why
Present the design in sections scaled to their complexity, confirming after each
Write the spec (see below), self-review it, and hand it to the user to review
On approval, hand off: /ticket where the work is a Jira story, otherwise implement directly

Design principles

YAGNI ruthlessly. Strip unnecessary features from every approach before presenting it.
Shape the modules deliberately. When the design turns on where a seam goes, how deep a module should be, or what its interface exposes, call the Skill tool with "codebase-design" and use that vocabulary rather than inventing terms here.
Name things in the project's language. When a term proves fuzzy or overloaded mid-interview, call the Skill tool with "domain-modeling" and settle it rather than working around it.
In an existing codebase, follow the existing patterns. Where code in the way of the work has a real problem (a file grown too large, tangled responsibilities), fold a targeted improvement into the design, the way a good developer improves code they are working in. Propose no unrelated refactoring.
Decompose before refining. If the request spans several independent subsystems, flag it immediately rather than spending a round on the details of something that needs splitting first. Each sub-project earns its own design cycle.
Visual questions get mocks, not prose. Where the open question is what something should look like, stop describing it: build several distinct static mocks, serve them, report the URL, and wait for a pick. Never edit a real component to answer a layout question.

The written spec (architectural only)

Write it to .claude/docs/specs/YYYY-MM-DD-<topic>.md, unless the work is a Jira story, in which case the ticket skill owns the artifacts and their location.

Then review it with fresh eyes and fix inline, no second pass:

Placeholders: any TBD, TODO, or vague requirement left in it?
Internal consistency: do any two sections contradict, and does the architecture match the feature descriptions?
Scope: focused enough to implement in one go, or does it still need decomposition?
Ambiguity: could any requirement be read two ways? Pick one and make it explicit.

Then hand it over and wait:

"Spec written to <path>. Have a read and tell me what you want changed before we build anything."

Red flags

Thought	Reality
"This is too simple to need a design"	Simple means a short design, not none. Two sentences, then approval.
"I'll call it bounded and skip the write-up"	Reaching for a label to skip work is the doubt. Take the heavier path.
"The design is obvious, I'll start while they read it"	The gate is the approval, not the design's length. Present, then stop.
"I know this kind of app, so it's bounded"	Bounded measures the repo, not your familiarity. No existing flow means architectural.
"The spike works, so I'll keep the code"	A spike's output is an answer. Keeping the code is a new request: classify it.
"It grew, but I'm nearly done, no need to re-classify"	Hidden complexity upgrades the path mid-task. Stop and say so.
"They approved the spike, so the follow-up is approved"	Every task gets its own classification and its own approval.
"I'll ask them what the config file says"	Facts are your job. Dispatch a subagent and find out.

Done when

The path was classified out loud, and upgraded if complexity appeared.
The frontier is empty: no branch of the design tree left unvisited, nothing silently assumed.
Every question asked was a decision, and every fact was looked up rather than asked.
The user has explicitly approved the design. Nothing was built before that.

8.4 KiB Raw Permalink Blame History