Groundwork

groundwork

!checklist init ${CLAUDE_SKILL_DIR} --force

Building the wrong thing well is the most expensive mistake in software, and an agent's strongest instinct — implement the literal ask — walks straight into it. This skill is the discipline that runs before code: discover the real need, the people it touches, the unspoken constraints, and the explicit edges of scope. Requirements work is a collaboration — you supply systematic rigor, the user supplies domain truth and the stakes.

This skill walks an explicit five-stage flight plan and will not fly past a GATE until it is cleared.

Discipline: finish every GATE before entering the next stage. GATEs are hard — never skip, batch past, or self-certify a stage you have not actually done. The checklist tool enforces the order; let it. Commands address stages by name, so you never have to track a number.

The agent's special handicap: you cannot walk the floor, run a workshop, or interview the silent stakeholder. So you must enlist the user as proxy for everyone the requirement touches, and you must read what can be read — the existing code, docs, tickets, competitors. Read references/agent-blind-spots.md first; it names the failure modes this skill exists to stop.

Speak the user's language, or the proxy breaks. The user can only stand in for the stakeholders if they actually follow you. Read their domain fluency from how they talk in STAGE 0, and match it — when a technical term or acronym first appears (SSRF, BYOK, p95, idempotent), gloss it in half a sentence. Skipping that is not brevity; it buys a confirmation that confirms nothing — a user nodding at words they did not parse, which makes STAGE 3's "what I understood = what you want" check pass falsely.

When there is no human in the loop (design-only). Sometimes no user is reachable for the whole run — you are scoping an OSS feature from an RFC, or designing against a written spec alone. The skill still applies, in a shifted mode: the invariant never guess silently on a high-blast-radius unknown still binds — its satisfaction shifts from get a yes to park the unknown as a named open question with an owner-to-ask and its blast-radius-if-wrong. Re-point the validation oracle from user intent to the best available written authority (the RFC, an enumerated reviewer comment, a standard like RFC 7519, the existing code) — see the WRITTEN-PROXY rule in references/decision-tree.md. STAGE 3 (Validate) then degrades to replay every Must against its written source + walk the full review checklist + park the unconfirmable; STAGE 4 (Manage) produces a proposed governance contract for whoever inherits the work, not a live authority gate. This is a weaker claim than user-confirmed understanding — label it as such in the handoff. The conservative-default FALLBACKs scattered through the references are this one mode; read them as one.

If $ARGUMENTS names a target to scope, scope that. If the ask is already a fully-pinned, low-risk change (a one-line fix, a rename), this skill is overkill — say so and proceed without it. When in doubt, open the decision tree.

The reference library

The depth lives in references/. Open each one when a stage sends you there — not all upfront.

• references/decision-tree.md — the engine. Is this even a requirements situation? How deep do you go? How does an agent stand in for stakeholders it cannot interview? Open it at the start and keep it beside you.
• references/agent-blind-spots.md — the failure modes an agent must be told: implementing the literal/solution-shaped ask, skipping stakeholder discovery, ignoring non-functional and implicit needs, gold-plating, silent scope creep, treating requirements as one-shot. Load at the start, re-check at every gate.
• references/elicitation.md — stakeholder discovery, digging the why under a stated solution, surfacing implicit requirements, and the methods (interview, observe, prototype-to-react-to) — adapted for an agent who interviews through the user.
• references/analysis.md — functional vs non-functional (with an NFR catalog), MoSCoW prioritization, surfacing stakeholder conflicts, and drawing the scope / out-of-scope line that fights scope creep.
• references/specification.md — user stories + INVEST, acceptance criteria (Given/When/Then), use cases, the six quality attributes, and the vague-word → measurable conversion that makes a requirement testable.
• references/validation-and-management.md — confirming "what you understood = what they want", and then the change process + traceability that accept requirements will evolve.

STAGE 0 — Elicit (gather: who to ask, and what they really need)

Do not design or estimate yet. First, who: build a stakeholder map — direct users, the funder/sponsor, operators, compliance/legal, and the silent-but-affected. A missed requirement is usually a missed person, not a missed analysis. You cannot interview them, so ask the user to identify and speak for them.

Then, what they really need: a stated solution is not a requirement. When the ask is solution-shaped ("I want an export button"), step back and dig for the why ("every month I have to hand my boss a report") — see the five-whys technique in references/elicitation.md. And surface implicit requirements — the things nobody says because they seem obvious (don't lose data, don't store passwords in plaintext). Their absence is an incident, not a feature gap.

Pull from every cheap source: the user's words, the existing system/code, tickets, competitors.

GATE — clear before STAGE 1

1. checklist check elicit stakeholders-mapped
2. checklist check elicit real-need-surfaced
3. checklist verify elicit

STAGE 1 — Analyze (sort by importance, expose the contradictions)

Open references/decision-tree.md and references/analysis.md.

Split functional from non-functional. Functional = what the system does; non-functional = performance, security, reliability, usability, scalability, compliance, observability. NFRs are the most-skipped class and the one that most often decides the architecture — surface them now, not after the design is set. Run the NFR sweep in analysis.md deliberately; do not wait for the user to volunteer them.

Prioritize. Resources never suffice. Rank with MoSCoW (Must / Should / Could / Won't). "Everything is important" is a planning failure.

Surface conflicts. Different stakeholders will contradict each other (more features vs. more stability). Put the conflict on the table now; resolving it in development is rework.

Draw the scope line. Writing down what is out of scope — explicitly, in black and white — is the single most effective weapon against scope creep. Do it here.

GATE — clear before STAGE 2

1. checklist check analyze functional-nonfunctional-split
2. checklist check analyze prioritized-and-scoped
3. checklist verify analyze

STAGE 2 — Specify (turn the fuzzy into the executable)

Open references/specification.md. Capture requirements in the right vessel — user stories + acceptance criteria, use cases, or a short SRS, as the scale warrants.

Every requirement must clear the quality bar: unambiguous, verifiable, necessary, feasible, consistent, traceable. The keystone is verifiable — after writing each one, ask "how would I test that this passed?" If you cannot answer, it is still too fuzzy.

Kill the vague words. "Fast", "user-friendly", "efficient", "robust", "scalable" are not requirements until quantified. "Responses should be fast" → "p95 response time < 200 ms under N concurrent users". Each funded requirement gets concrete acceptance criteria (Given/When/Then) that double as the validation contract for the next stage.

GATE — clear before STAGE 3

1. checklist check specify requirements-verifiable
2. checklist check specify acceptance-criteria-defined
3. checklist verify specify

STAGE 3 — Validate (confirm everyone understood the same thing)

Written does not mean correct. Close the loop with the user/stakeholders: walk the requirements and their acceptance criteria back to them, demo a prototype or wireframe where words are slippery, and confirm that what you understood is what they want. Every misunderstanding caught here saves multiplied rework downstream — see references/validation-and-management.md.

If validation exposes a gap, go back — re-elicit or re-analyze — rather than paper over it.

GATE — clear before STAGE 4

1. checklist check validate shared-understanding-confirmed
2. checklist check validate high-blast-unknowns-parked
3. checklist verify validate

STAGE 4 — Manage (requirements will change — plan for it)

Open references/validation-and-management.md (PART TWO). Requirements are not carved once. Establish a lightweight change process (who can change a requirement, how its impact is assessed, how the change is recorded) and traceability — ideally every requirement traces down to its design, code, and tests, so a change here tells you what it touches there. Record a baseline, the residual risk, and any open questions so whoever inherits this work inherits the map too.

FINAL GATE

1. checklist check manage change-and-traceability
2. checklist verify manage
3. checklist show — confirm all five stages passed.
4. checklist done — clear this run's state.

Handoff to building

Groundwork's output is the contract the build honors. When you proceed to implement (and, later, to test — see the assay skill), carry the funded requirements, their acceptance criteria, and the out-of-scope list forward verbatim. The acceptance criteria you wrote in STAGE 2 are exactly the oracles a test suite needs.

Anti-patterns (use as a pre-flight checklist)

• Solution-as-requirement — implementing the stated fix without digging for the underlying need. The single most common agent failure. (agent-blind-spots.md BS-1)
• Scope creep — requirements quietly accreting with no one calling stop. The out-of-scope list is the brake. (BS-5)
• Gold plating — adding capability the user never asked for; it buys complexity and bugs, not value. (BS-4)
• Listening only to the loudest — the silent stakeholder's missing requirement sinks the project just as hard. (BS-2)
• Ignoring non-functional requirements — remembering high-concurrency or compliance only after the architecture is poured. (BS-3)
• The waterfall illusion — believing requirements can be gathered once and frozen; they evolve, so manage them. (BS-6)
• Unverifiable requirements — "fast", "friendly", "robust" with no number; if you can't test it, you can't build to it. (BS-8)
• Skipping a GATE — the user's judgment at each gate can change the whole plan.

The BS-* tags point to the deep cards in references/agent-blind-spots.md, each with the corrective behavior and a literal "do this".