Grill Me

Interview the user about their plan or design until you have enough shared understanding to produce technically complete specification documents. These documents are the single source of truth for ticket creation — they must contain everything an autonomous agent needs to implement the feature correctly, including all integration boundaries, third-party constraints, and non-obvious framework patterns.

If any of that information ends up in a ticket but not in the spec, the spec has failed.

Principles

• Ask one question at a time. Wait for the answer before moving on.
• For each question, provide your recommended answer based on codebase research and good engineering judgment. The user should only need to confirm, correct, or elaborate.
• If a question can be answered by reading the codebase, read it instead of asking.
• Work down the decision tree branch by branch — do not skip ahead.
• Do not stop until every area below has been covered. Push back on vague answers.

---

Phase 1 — Product Intent

Cover the user's goals, user journeys, and success criteria before touching implementation.

Ask about:

• Who is this feature for — which users, in which context?
• What problem does it solve? What is the user trying to do before this exists, and what becomes possible after?
• The happy path end-to-end, described as a user journey in plain language.
• Non-happy-path flows — what happens when:
  • The operation fails partway through?
  • The data is empty or not yet ready?
  • The user has no permissions?
  • A background process is still running when the UI loads?
  • The operation takes longer than expected?
• Success criteria — how will you know it works? What should a tester do to verify it?
• Scope boundaries — what is explicitly out of scope for v1?

---

Phase 2 — Architecture and Integration Boundaries

Map every layer the feature touches and the contract between them. The output of this phase becomes the architecture.md document — it must be precise enough that a ticket can simply quote from it rather than requiring the ticket author to re-research anything.

2a. Data layer (if backend touches DB)

• What new tables or columns are needed?
• What is the complete set of repository methods every consumer of this layer will need — including consumers outside this feature (background jobs, pruning workflows, admin tools, future features)? For each: name, parameter types, and return type.
• Are there bulk insert, update, or delete operations? Do they need to be transactional?
• Are there queries that build result objects inside loops or map callbacks? Check the project's lint rules for constraints on how objects can be constructed in these contexts. Document the required pattern.

2b. Background jobs and async processing (if applicable)

• What jobs, workers, or scheduled tasks does this feature involve?
• What is the data flow between processing steps at scale? If a step receives data from a previous step, how large is that data for a representative workload? Is it safe to pass as in-memory payload, or must it be read from the DB using a shared identifier?
• For every third-party service or messaging system involved: document the relevant constraints now, before the architecture is designed. This includes: payload size limits, rate limits, timeout limits, retry semantics, idempotency requirements, authentication patterns. These are not implementation details — they are architectural constraints.
• What does the DB state look like while a job is running / complete / failed?
• What is the failure and retry behaviour?

2c. Backend API

• What new endpoints are needed? For each: HTTP method, URL, auth requirement, full request schema, full response schema (including all nullable and array fields).
• Which existing endpoints are modified?
• How does the framework discover and register routes? Document whether any new route file requires explicit registration, and where. (In this codebase: route files are not auto-discovered — each must be registered in apps/backend/src/routes/v1/index.ts.)
• Are there any codegen or type-sync steps that must be run after API changes, and must be committed? (In this codebase: bun run api:sync regenerates openapi.json and apps/frontend/src/lib/api/types.d.ts.)

2d. Frontend data loading

• Which routes load data? Do any use URL search params to drive what data is fetched?
  • If yes: document the exact framework pattern required. (In this codebase: TanStack Router requires loaderDeps: ({ search }) => search, and the loader receives deps not search.)
• For any library wrapping API calls: document its exact return contract, especially if it differs from what the library name implies. Library versions frequently have non-obvious differences. (In this codebase: openapi-react-query v0.5.1's ensureQueryData returns the raw response body — not { data, error }.)
• What query options functions are needed? Where do they live?

2e. Frontend components

• Which pages or routes are new? Which are modified?
• For each new page: what is the full component tree?
• For each view: what are the loading, error, empty, and data-ready states? All four must be explicitly defined — no "TBD" states.
• Are any user-visible strings subject to feature flags or runtime configuration? Document the resolution pattern. (In this codebase: tile/plugin terminology uses useTileTerminology() in components and getTileTerminology() in loaders.)

---

Phase 3 — Operability

Features are not complete if they cannot be operated in production.

Ask about:

• Data lifecycle — does any data expire, become stale, or accumulate unboundedly? How is it cleaned up, and who owns that path?
• Background jobs / schedules — timing, concurrency limits, retry limits, and failure alerting for each.
• Rate limiting — are any endpoints publicly accessible or called at high frequency? Where is rate limiting enforced?
• Monitoring — what analytics events or metrics indicate the feature is healthy? What does anomalous behaviour look like?
• Rollback — if this needs to be disabled, what is the path? Is there a feature flag?

---

Phase 4 — Spec Completeness Check

Walk through every user-visible element and confirm it is fully specified.

For each screen, widget, or API endpoint:

• Is the complete field list defined (including nullables, empty arrays, and edge case values)?
• Is there a specified empty state?
• Is there a specified loading state?
• Is there a specified error state?
• Is sort order and pagination behaviour defined?
• Are there any open design decisions that require human input before implementation? Mark these explicitly as [HITL] — they must not be answered autonomously by an agent.

---

Phase 5 — Coverage Mapping

Before ending the interview, build a table mapping every user-visible feature and background concern to the part of the implementation that covers it:

Any row with no owner is a gap. Do not end the interview until every row has an owner.

---

Output

Produce the following documents in docs/<feature-name>/:

1. README.md — feature overview: what it is, why it exists, the user journey, and the scope boundary.

2. v1-user-journey.md — the full happy path and all non-happy-path flows, written from the user's perspective.

3. v1-[area].md for each major area (e.g. v1-dashboard.md, v1-ingest.md) — detailed spec including exact field names, response shapes, component trees, all four component states, and open decisions flagged as [HITL].

4. architecture.md — the technically complete integration map. This document must contain:

   • Every layer involved and what it produces and consumes
   • The complete repository interface (all method names and signatures)
   • The complete API interface (all endpoints, request/response shapes)
   • The data flow between processing steps, including any volume or size considerations
   • All third-party service constraints that affect the design
   • All non-obvious framework patterns required by this feature
   • Any project lint rules that constrain implementation in this area
   • Any codegen or sync steps required after changes

   This document is what makes ticket creation a translation job rather than a research job. It must be thorough enough that no ticket author needs to explore the codebase to fill in missing information.