claude-spec-interviewer

# Identity

You are Claude Code acting as a careful software engineering agent inside `{{REPO_NAME}}`.

# Goal

Implement the attached or referenced spec exactly, with minimal scope creep and clear verification.

# Instructions

- Treat the spec as the primary task contract.
- Read the spec from `{{SPEC_PATH}}` when a path is provided; otherwise use the attached spec content.
- Treat the source challenge findings as part of the task contract.
- Treat referenced ADRs and ADR gate results as architectural constraints.
- Treat the user verification record as the boundary of approved scope, not as implementation authorization by itself. Execute only when implementation is separately authorized; reuse that existing authorization without asking again.
- Read repository instructions such as `AGENTS.md` before editing.
- For medium or larger work, create and maintain a short plan before making code changes.
- Prefer the repository's existing patterns and abstractions over inventing new ones.
- If repository reality materially conflicts with the approved spec, report the affected difference and resolve it before that implementation; do not silently change the approved scope.
- If repo reality or current docs contradict a challenged requirement, stop and report the conflict before implementing that part.
- Make the smallest safe change that satisfies the spec.
- Do not implement explicit non-goals.
- If implementation depends on a proposed or unresolved ADR, stop before implementing the blocked portion.
- Add or update tests when the change affects behavior.
- Run the validation commands listed in the spec.
- Review the final diff for regressions, risky patterns, and accidental extra edits.

# Output contract

Return:

1. Summary of what changed
2. Files changed
3. Validation results
4. Any conflicts between the spec and repo reality
5. Remaining risks or follow-up items

# Context

<implementation_spec>
{{SPEC_CONTENT}}
</implementation_spec>

---
title: "Replace legacy fetchJson wrapper with typed apiClient across the repo"
slug: "typed-api-client-repo-refactor"
artifact_path: "docs/specs/typed-api-client-repo-refactor-spec.md"
mode: "deep"
status: "draft"
owner: "platform-foundation"
repo: "monorepo"
created: "2026-05-21"
updated: "2026-05-21"
source_request: "Refactor the repo to use the new typed API client instead of the old fetch wrapper"
phases: ["phase-1-safe-adoption", "phase-2-full-cutover"]
---

# Replace legacy fetchJson wrapper with typed apiClient across the repo

## Goal

Standardize HTTP access on the new typed `apiClient` abstraction to improve type safety, error consistency, retry handling, and maintainability, while minimizing regression risk during the migration.

## Background

The repository currently uses a mixture of `fetchJson(...)`, ad hoc `fetch(...)`, and service-local wrappers. This creates inconsistent error handling, duplicated headers, and weak typing at call sites. The new `apiClient` already exists but is only partially adopted.

## Scope

### In scope

- migrate direct `fetchJson(...)` call sites to `apiClient`
- align common error handling on the `apiClient` response/error model
- update affected tests and mocks
- preserve current user-visible behavior

### Non-goals

- redesign backend APIs
- rename domain models unrelated to the migration
- perform unrelated cleanup in touched files
- replace transport behavior that is intentionally service-specific

## Repo context

- Relevant packages/services/modules:
  - `packages/api-client/`
  - `apps/web/`
  - `apps/admin/`
  - `packages/test-utils/`
- Current architecture and seams:
  - shared HTTP utilities live in `packages/api-client`
  - some apps still import `fetchJson` from legacy utility modules
- CI/build/test expectations:
  - lint, typecheck, unit tests, and affected integration tests must pass
- Unknowns:
  - full inventory of remaining `fetchJson` usage is unspecified before code search

## Requirements

### Functional requirements

- WHEN a module currently uses `fetchJson(...)`, THE SYSTEM SHALL migrate it to `apiClient` unless a documented exception applies.
- WHEN a migrated call previously returned typed domain data, THE SYSTEM SHALL preserve the same effective runtime behavior while improving compile-time typing.
- IF the old call path relied on custom headers, auth propagation, or retries, THEN THE SYSTEM SHALL preserve that behavior after migration.
- IF a call site cannot be safely migrated in this pass, THEN THE SYSTEM SHALL be left unchanged and documented as deferred.

### Non-functional requirements

- Performance: no materially worse request fan-out or duplicate calls.
- Reliability: preserve timeout/retry behavior where it already exists.
- Security/privacy: preserve auth headers, CSRF handling, and redaction rules.
- Observability: preserve or improve request error logging.
- Backward compatibility: no user-visible API contract changes.

## Design

### Proposed architecture

- `apiClient` becomes the default shared abstraction.
- Legacy `fetchJson` remains only as a temporary compatibility shim during the migration window.
- Shared test helpers and mocks are updated first so downstream migrations become cheaper.
- Service-specific adapters may wrap `apiClient` if a domain needs typed helper methods.

### Alternatives considered

- Big-bang removal of all legacy wrappers in one PR:
  - rejected because review size and regression risk are too high.
- Permanent dual-stack support:
  - rejected because it keeps error semantics inconsistent.
- Per-app independent migration strategies:
  - rejected because shared consistency is the point of the refactor.

## Architectural decisions

- ADR required: yes, if `apiClient` is not already the accepted shared HTTP abstraction.
- Existing ADRs consulted: check for API-client or transport ADR before implementation.
- ADR draft or path: `docs/adrs/NNNN-use-typed-api-client.md` if no accepted ADR exists.
- Supersedes: any accepted ADR that requires permanent legacy `fetchJson` usage.
- Implementation blocked until ADR accepted: yes for repo-wide cutover; no for inventory-only work.

## Source challenge

- Repo evidence checked:
  - inventory current `fetchJson(...)` call sites before deciding migration phases
  - inspect `apiClient` behavior, shared mocks, and test utilities before replacing call sites
- ADRs/specs checked:
  - check for any API-client or transport ADR before finalizing the migration contract
- External docs checked:
  - check current framework/runtime fetch behavior only if `apiClient` depends on changed platform semantics
- Requirements revised:
  - defer call sites with undocumented service-specific behavior
- Requirements preserved:
  - preserve auth, headers, retry behavior, and user-visible runtime behavior
- Preceding ADR/spec work needed:
  - add an ADR or migration note if `apiClient` is not already the accepted default abstraction
- ADR gate result:
  - unresolved until existing ADRs and `apiClient` ownership are checked
- Skipped checks and why:
  - package-specific external docs are unnecessary until the concrete `apiClient` implementation is inspected

## User verification

- Final checkpoint confirmed by: platform owner
- Confirmation date: 2026-05-21
- Verified scope/non-goals:
  - migrate safe call sites, preserve runtime behavior, and defer service-specific exceptions
- Verified rollout/rollback assumptions:
  - cutover proceeds in phases and implementation remains blocked where a required ADR is unresolved
- Non-blocking open questions accepted:
  - exact call-site inventory is completed during phase 1 before code changes

## File and module plan

### Expected touched areas

- `packages/api-client/**`
- `packages/test-utils/**`
- `apps/web/**`
- `apps/admin/**`

### Expected new files

- migration inventory note if needed:
  - `docs/adrs/` or `docs/migrations/typed-api-client.md`
- targeted helpers/tests only if required

### Explicitly protected areas

- backend services
- public API schema definitions
- unrelated UI state management

## Artifact plan

- Spec path: `docs/specs/typed-api-client-repo-refactor-spec.md`
- Destination basis: existing `docs/specs/` convention; ADR path requires confirmation if a new ADR is needed
- Explicit confirmation needed: yes, for ADR creation or ambiguous API-client ownership
- Spec persistence: saved
- Existing file overwrite needed: no
- ADR paths:
  - `docs/adrs/NNNN-use-typed-api-client.md` if no existing ADR covers the default transport abstraction
- ADR persistence: blocked until existing ADR coverage and API-client ownership are confirmed
- ADR index updates needed: yes when a new ADR is saved
- Companion execution prompt path or embedding: embed with saved spec unless the repo already stores execution prompts separately

## Task breakdown

### Phase 1

- inventory all `fetchJson` call sites
- migrate shared mocks/helpers to support `apiClient`
- migrate low-risk leaf modules first
- add lint rule or grep-based guard to prevent new `fetchJson` usage

Validation gate:

- typecheck passes
- migrated leaf modules pass tests
- no net-new legacy call sites appear

### Phase 2

- migrate remaining app call sites module by module
- preserve service-specific behaviors with adapters where necessary
- leave deferred exceptions documented with reasons
- reduce legacy wrapper to compatibility-only or remove if zero usages remain

Validation gate:

- full test suite passes
- search confirms expected usage count
- diff review confirms no unrelated scope expansion

## Validation

```bash
pnpm lint
pnpm typecheck
pnpm test
rg "fetchJson\\(" .
```

### Manual verification

- Verify login/authenticated flows still send expected auth context.
- Verify representative success and error flows in web and admin apps.
- Verify test mocks and fixtures still match runtime request shape.

### Review focus

- silent error-shape drift
- auth/header propagation regressions
- duplicated requests or retry regressions
- accidental scope creep in touched files

## Rollout and rollback

- Rollout strategy:
  - merge in phases, not one giant refactor
- Feature flag:
  - not required unless runtime path selection is introduced
- Data migration/backfill:
  - none expected
- Monitoring during rollout:
  - watch request error rates and auth-related failures
- Rollback trigger:
  - elevated request failures, auth regressions, or broad integration breakage
- Rollback procedure:
  - revert the current migration slice, keep already-stable shared helper changes if isolated and safe

## Risks

| Risk                                     | Why it matters                                                  | Mitigation                                    |
| ---------------------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
| hidden service-specific wrapper behavior | a naive replacement can break retries/headers/error translation | inventory and preserve behavior before swap   |
| too-large PRs                            | review quality and regression risk collapse                     | phase the migration by package or module      |
| mock drift                               | tests pass for the wrong reason or start failing everywhere     | migrate shared test utilities first           |
| partial cutover confusion                | engineers may keep adding legacy calls                          | add a guardrail and document the default path |

## Done when

- [ ] All planned modules are migrated or explicitly deferred
- [ ] No unintended user-visible behavior changed
- [ ] Validation commands pass
- [ ] Remaining exceptions are documented
- [ ] Legacy abstraction is either compatibility-only or removed where safe

## Assumptions and open questions

- Assumption: `apiClient` already exists and is preferred by maintainers.
- Assumption: phase-based migration is acceptable.
- Open question: whether a repo-level lint guard already exists for legacy wrapper usage.
- Open question: whether any package intentionally depends on fetch-specific semantics that `apiClient` does not yet expose.

---
title: "Add CSV export to admin users table"
slug: "admin-users-csv-export"
artifact_path: "docs/specs/admin-users-csv-export-spec.md"
mode: "compact"
status: "draft"
owner: "admin-platform"
repo: "web-app"
created: "2026-05-21"
updated: "2026-05-21"
source_request: "Add CSV export for the users admin view"
---

# Add CSV export to admin users table

## Goal

Allow admins to export the currently filtered users table as a CSV file from the existing admin users page without changing table behavior or exposing sensitive fields.

## Scope

- In scope:
  - add one export action to the admin users page
  - export only the rows that match the current filters
  - include a stable CSV column order
- Out of scope:
  - background jobs
  - XLSX export
  - new permissions model

## Repo context

- Relevant files or areas:
  - `src/pages/admin/users.tsx`
  - `src/components/admin/UsersTable.tsx`
  - `src/lib/csv.ts` if it exists, otherwise add a local helper
- Existing commands or conventions:
  - use the existing admin action button pattern
  - keep current filter state as the export source of truth
- Unknown repo facts marked as unspecified:
  - exact shared CSV helper availability is unspecified

## Requirements

### Functional requirements

- WHEN an admin is on the users page, THE SYSTEM SHALL show an `Export CSV` action near the table controls.
- WHEN the admin clicks `Export CSV`, THE SYSTEM SHALL download a CSV containing only the rows matching the current filters.
- WHEN the table is empty after filters are applied, THE SYSTEM SHALL still download a CSV containing headers only.
- IF a field is sensitive or internal-only, THEN THE SYSTEM SHALL exclude it from the export.

### Constraints

- Keep current table rendering and filter logic unchanged.
- Do not add server-side export infrastructure.
- Exclude password hashes, internal tokens, notes, and raw audit blobs if present.
- Preserve existing admin-page styling and button placement conventions.

## File plan

- Update:
  - `src/pages/admin/users.tsx`
  - `src/components/admin/UsersTable.tsx`
- Add:
  - `src/lib/exportUsersCsv.ts` if no existing helper is suitable
- Avoid touching:
  - auth flows
  - user-edit forms
  - backend endpoints unless absolutely required

## Architectural decisions

- ADR required: no
- Existing ADRs consulted: none identified
- ADR draft or path: none
- Implementation blocked until ADR accepted: no

## Source challenge

- Repo evidence checked:
  - existing admin users page and table component should be inspected before implementation
  - current filter state must be confirmed as the export source of truth
- ADRs/specs checked:
  - none identified
- External docs checked or skipped:
  - skipped because CSV generation is local behavior unless the repo uses a shared export package
- Requirements revised:
  - none
- Requirements preserved:
  - export current filtered rows only
  - exclude sensitive/internal fields
- ADR gate result:
  - no durable architectural decision identified

## Validation

```bash
pnpm lint
pnpm test
pnpm exec playwright test admin-users-export.spec.ts
```

## Done when

- [ ] Admin users page shows an export action
- [ ] Downloaded CSV matches current filters
- [ ] Sensitive/internal fields are excluded
- [ ] Relevant automated checks pass

## Assumptions and open questions

- Assumption: current filter state is available client-side for export.
- Assumption: client-side CSV generation is acceptable for current dataset size.
- Open question: exact canonical list of exportable user columns is unspecified.

---
title: "<short human-readable title>"
slug: "<kebab-case-slug>"
artifact_path: "docs/specs/<kebab-case-slug>-spec.md"
mode: "compact"
status: "draft"
owner: "<person-or-team>"
repo: "<repo-name-or-path>"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
source_request: "<original request>"
---

# <title>

## Goal

<one paragraph describing the change and the user-visible outcome>

## Scope

- In scope:
- Out of scope:

## Repo context

- Relevant files or areas:
- Existing commands or conventions:
- Unknown repo facts marked as unspecified:

## Requirements

### Functional requirements

- WHEN <condition/event>, THE SYSTEM SHALL <expected behavior>.
- WHEN <condition/event>, THE SYSTEM SHALL <expected behavior>.

### Constraints

- Keep/change:
- Must not:
- Compatibility/performance/security constraints:

## File plan

- Update:
- Add:
- Avoid touching:

## Architectural decisions

- ADR required: yes/no/unresolved
- Existing ADRs consulted:
- ADR draft or path:
- Implementation blocked until ADR accepted: yes/no

## Source challenge

- Repo evidence checked:
- ADRs/specs checked:
- External docs checked or skipped:
- Requirements revised:
- Requirements preserved:
- ADR gate result:

## Validation

```bash
<lint command or "unspecified">
<test command or "unspecified">
<manual verification step>
```

## Done when

- [ ] Behavior matches the request
- [ ] Relevant checks pass
- [ ] No stated non-goal was implemented

## Assumptions and open questions

- Assumption:
- Open question:

---
title: "<short human-readable title>"
slug: "<kebab-case-slug>"
artifact_path: "docs/specs/<kebab-case-slug>-spec.md"
mode: "deep"
status: "draft"
owner: "<person-or-team>"
repo: "<repo-name-or-path>"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
source_request: "<original request>"
phases: ["phase-1", "phase-2"]
---

# <title>

## Goal

<full objective, business or engineering motivation, and definition of success>

## Background

- Current problem:
- Why current behavior/architecture is insufficient:
- Related history, ADRs, or prior attempts:

## Scope

### In scope

- <major workstream>
- <major workstream>
- <major workstream>

### Non-goals

- <explicit exclusion>
- <explicit exclusion>
- <explicit exclusion>

## Repo context

- Relevant packages/services/modules:
- Current architecture and seams:
- Shared libraries/contracts that constrain the change:
- CI/build/test expectations:
- Unknowns or facts that require confirmation:

## Requirements

### Functional requirements

- WHEN <condition/event>, THE SYSTEM SHALL <expected behavior>.
- WHILE <state/precondition>, THE SYSTEM SHALL <expected behavior>.
- IF <error/unwanted behavior>, THEN THE SYSTEM SHALL <expected behavior>.

### Non-functional requirements

- Performance and scalability:
- Reliability and failure handling:
- Security/privacy/compliance:
- Observability and diagnostics:
- Backward compatibility:

## Design

### Proposed architecture

- Components involved:
- Control/data flow:
- Interfaces/contracts to create or modify:
- Storage/schema/config changes:
- Deprecation or migration strategy:

### Alternatives considered

- Option A:
- Option B:
- Chosen because:

## Architectural decisions

- ADR required: yes/no/unresolved
- Existing ADRs consulted:
- ADR draft or path:
- Supersedes:
- Implementation blocked until ADR accepted: yes/no

## Source challenge

- Repo evidence checked:
- ADRs/specs checked:
- External docs checked:
- Requirements revised:
- Requirements preserved:
- Preceding ADR/spec work needed:
- ADR gate result:
- Skipped checks and why:

## User verification

- Reviewed revision and approval evidence:
- Approved scope, assumptions, risks and validation:
- Accepted non-blocking questions:
- Approved delivery, paths and concrete write actions:
- ADR decision acceptance, distinct from draft persistence:

## File and module plan

### Expected touched areas

- `path/to/package-a`
- `path/to/package-b`
- `path/to/shared-lib`

### Expected new files

- `path/to/new-file`

### Explicitly protected areas

- `path/to/avoid`

## Artifact plan

- Spec path:
- Destination basis: existing convention/suggested/user-provided/declined
- Outstanding write decisions, if any:
- Spec persistence: pending/saved/not requested/blocked
- Existing file overwrite needed: yes/no
- ADR paths:
- ADR persistence: none/pending/saved/not requested/blocked
- ADR index updates needed:
- Companion execution prompt path or embedding:

## Task breakdown

### Phase 1

- Task:
- Task:
- Validation gate:

### Phase 2

- Task:
- Task:
- Validation gate:

## Validation

```bash
<lint>
<typecheck>
<unit tests>
<integration tests>
<e2e tests>
<build command>
```

### Manual verification

- Scenario:
- Scenario:
- Scenario:

### Review focus

- Regression hotspots:
- Security review points:
- Migration sanity checks:

## Rollout and rollback

- Rollout strategy:
- Feature flag / canary / phased release:
- Data migration or backfill:
- Monitoring during rollout:
- Rollback trigger:
- Rollback procedure:

## Risks

| Risk   | Why it matters | Mitigation   |
| ------ | -------------- | ------------ |
| <risk> | <impact>       | <mitigation> |
| <risk> | <impact>       | <mitigation> |

## Done when

- [ ] Functional and non-functional requirements are met
- [ ] Planned phases are complete or explicitly deferred
- [ ] Validation commands pass
- [ ] Rollout notes are actionable
- [ ] Remaining open questions are documented

## Assumptions and open questions

- Assumption:
- Assumption:
- Open question:
- Open question:

---
title: "<short human-readable title>"
slug: "<kebab-case-slug>"
artifact_path: "docs/specs/<kebab-case-slug>-spec.md"
mode: "standard"
status: "draft"
owner: "<person-or-team>"
repo: "<repo-name-or-path>"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
source_request: "<original request>"
---

# <title>

## Goal

<clear problem statement, intended outcome, and why this work matters>

## Scope

### In scope

- <bounded work item>
- <bounded work item>

### Non-goals

- <explicit exclusion>
- <explicit exclusion>

## Repo context

- Relevant files/directories:
- Existing abstractions/patterns to preserve:
- Commands and toolchain:
- Related issue/ADR/PR:
- Unspecified facts:

## User-facing behavior

- User story:
- Primary flow:
- Failure/empty/loading states:
- Accessibility/localization/compatibility notes:

## Requirements

### Functional requirements

- WHEN <condition/event>, THE SYSTEM SHALL <expected behavior>.
- WHEN <condition/event>, THE SYSTEM SHALL <expected behavior>.
- IF <error/unwanted behavior>, THEN THE SYSTEM SHALL <expected behavior>.

### Non-functional requirements

- Performance:
- Reliability:
- Security/privacy:
- Observability/logging:

## Design notes

- Preferred implementation approach:
- Reuse before rewrite:
- Data/API/model changes:
- Tradeoffs considered:
- Follow existing repo conventions unless the spec says otherwise.

## Architectural decisions

- ADR required: yes/no/unresolved
- Existing ADRs consulted:
- ADR draft or path:
- Supersedes:
- Implementation blocked until ADR accepted: yes/no

## File plan

### Expected touched areas

- `path/to/file`
- `path/to/dir`

### Expected new files

- `path/to/new-file`

### Areas not to change

- `path/to/keep-stable`

## Execution plan

1. Confirm the current implementation and extension points.
2. Implement the minimal code changes for the happy path.
3. Add or update tests.
4. Handle error/edge states.
5. Run validation commands.
6. Review for regressions and scope creep.

## Source challenge

- Repo evidence checked:
- ADRs/specs checked:
- External docs checked:
- Requirements revised:
- Requirements preserved:
- Preceding ADR/spec work needed:
- ADR gate result:
- Skipped checks and why:

## User verification

- Reviewed revision and approval evidence:
- Approved scope, assumptions, risks and validation:
- Accepted non-blocking questions:
- Approved delivery, paths and concrete write actions:
- ADR decision acceptance, distinct from draft persistence:

## Artifact plan

- Spec path:
- Destination basis: existing convention/suggested/user-provided/declined
- Outstanding write decisions, if any:
- Spec persistence: pending/saved/not requested/blocked
- Existing file overwrite needed: yes/no
- ADR paths:
- ADR persistence: none/pending/saved/not requested/blocked
- ADR index updates needed:

## Validation

```bash
<install-free verification commands>
<lint>
<typecheck>
<unit/integration tests>
```

### Manual checks

- Verify:
- Verify:
- Verify:

## Risks and rollout

- Primary risk:
- Rollback path:
- Migration/backfill needs:
- Feature-flag or phased rollout need: yes/no

## Done when

- [ ] All functional requirements are met
- [ ] Non-goals remain untouched
- [ ] Validation commands pass
- [ ] Manual checks pass
- [ ] Risks and follow-up notes are documented

## Assumptions and open questions

- Assumption:
- Assumption:
- Open question:

# ADR Gate

Use this gate before finalizing the implementation spec. ADRs are for durable architecture and repo-level decisions, not feature notes.

## Create or Draft an ADR When

The spec depends on a new, changed, or superseded decision about:

- package, module, service, or ownership boundaries,
- dependency direction or shared abstraction policy,
- runtime, framework, storage, queue, or external service choice,
- public/shared API contracts,
- data ownership, schema, migration, or compatibility strategy,
- auth, security, permission, or privacy model,
- repo-wide validation, build, deployment, publishing, or release policy,
- replacing or superseding an existing ADR.

## Do Not Create an ADR For

- feature-specific behavior,
- UI copy, layout, or interaction details,
- one-off implementation choices under existing architecture,
- routine refactors that preserve current boundaries,
- test cases, validation commands, or rollout checklist items,
- temporary experiments or prototypes.

## Gate Output

Include this result before the final spec:

```md
## ADR gate

- ADR required: yes/no/unresolved
- Reason:
- Existing ADRs consulted:
- New ADR draft:
- Supersedes:
- Implementation blocked until ADR accepted: yes/no
```

## If ADR Is Required

1. Draft exactly one architectural decision per ADR.
2. Use the repository ADR template and required linked representations; do not impose a numeric word or section limit.
3. Mark status as `Proposed` unless the maintainer explicitly accepts the reviewed decision. Permission to save a proposed ADR is distinct from accepting its decision; preserve prior acceptance when unchanged.
4. Use the repo ADR filename pattern. If no pattern exists, use `NNNN-kebab-title.md` with the next sequential number.
5. Resolve missing ADR directories in the same concrete final checkpoint, reusing earlier directory-creation authority.
6. Persist the ADR when required and report its path. While the current execution host's Plan mode is active, defer this write to the save-only continuation. During persistence, update the repository's existing ADR index when its convention requires one; treat that minimal entry as part of ADR persistence, not unrelated documentation.
7. Reference the ADR from the implementation spec.
8. If the spec depends on ADR acceptance, mark implementation as blocked or phased.

## Spec Linkage

The final spec should include an `Architectural decisions` section:

- `ADR required: no` for feature-only work.
- `ADR draft: <title>` when the decision is proposed but not saved.
- `ADR path: docs/adrs/NNNN-title.md` when the ADR exists.
- `Implements: ADR-XXXX` when the spec implements an accepted decision.

Do not re-litigate accepted ADRs during implementation unless repo reality or current sources contradict them.

# Artifact destinations

Use when selecting delivery and concrete spec/ADR paths. Reuse the request, prior answers and exact write authority; do not restart permission discovery at finalization.

## Discover delivery and paths

1. Default to a repository-owned saved spec; explicit chat-only delivery takes precedence without a persistence question. Carry existing save authority forward and identify the path while interviewing.
2. Use an explicit path first, then a clear repository convention. If neither exists, propose `docs/specs/<kebab-slug>-spec.md`.
3. Inspect public/private placement, directory existence and existing destination content. Raise material ambiguity early or include it in the final checkpoint. Do not interrupt merely to confirm a clear existing convention.
4. Include unapproved directory creation, overwrites, required ADR writes and minimal ADR index updates in the same concrete checkpoint. Previously approved actions do not need another question unless their scope or target state changed.

In this `agent-skills` repository, follow `docs/specs.md`: use the ignored `docs/specs/do-not-publish/` for private, exploratory, sensitive, repository-creation, or not-yet-public specs. Use public `docs/specs/` only after the maintainer explicitly confirms publishability. In other repositories, local conventions take precedence. An intentionally local-only artifact does not require a new sharing question; ask only when an ignored destination conflicts with the requested shared result. Never unignore a path implicitly.

Use lowercase kebab-case names ending in `-spec.md` unless the repository requires another format. Do not add sequential numbers unless the repository does.

## Approve and persist

Follow [workflow-details.md](workflow-details.md): prepare the complete reviewable content, then combine content approval and outstanding concrete write decisions into one positive checkpoint. A mode toggle alone is not approval. Do not overwrite a file merely because the slug matches; inspect its content and reuse only authority that covers that content/state.

Native Plan permits no repository persistence. Keep an approved result pending until actual exit and known write permissions, without asking approval again. During save-only finalization write only the spec, required ADR and minimal convention-required ADR index entry; capture other documentation work in the spec for later implementation. Read back saved artifacts and report actual paths. Explicit chat-only output completes the requested delivery; a blocked requested save remains incomplete.

## ADR destinations and status

Follow the repository's ADR directory, linked representations, template, numbering and index. Keep one durable decision per ADR. Default to `Proposed` unless the maintainer explicitly accepts the reviewed decision. Approval to save a proposed ADR is not decision acceptance. Carry prior acceptance forward when unchanged. Link required ADRs from the spec and block dependent implementation until acceptance.

# Execution-host adapters

Load this reference only when a native control or transition matters. The skill's target runtime does not determine the execution host. A Claude Code-ready spec can be interviewed in Codex without Claude-only controls, and vice versa.

## Capability evidence

Use current runtime context and exposed tools first. A product label, model name, documentation page, `/goal`, installed plan skill, or user text requesting “plan” does not prove native Plan is active. Documentation describes possible controls; it is not live-client evidence. When useful, record `surface`, `experience`, `plan_control`, `plan_state`, `evidence_source`, `host_version`, and `confidence`; unknown values remain unknown. Do not stop a read-only interview merely to complete this record.

Keep `Planning capability:` and `Read-only enforcement:` independent. Available but inactive and indeterminate planning both permit non-mutating discovery and conversation under the behavioral no-write gate. Do not call missing controls “unavailable” without evidence, nor treat an explicit refusal as technical absence. A busy composer cannot prove the control is absent; continue independent reads while any requested transition remains pending.

## Codex execution host

Use `request_user_input` when exposed and allowed by its current mode contract; use an asynchronous question control only when actually available and appropriate. Otherwise ask conversationally. Native mode is host-controlled: use an exposed transition or exit control according to its contract, or request the observed manual action only when that action is needed. Do not claim that sending text changed modes.

For a CLI that documents and exposes `/plan`, a standalone command is a valid manual option. Combining it with `$codex-spec-interviewer` and an inline prompt requires evidence that this client supports inline arguments; do not transfer CLI parsing assumptions to a different surface. Preserve the original request in conversation rather than making the user retype it.

## ChatGPT and Codex web execution hosts

Distinguish ChatGPT Chat/Work from Codex web only as needed to choose a real control. If the surface or experience is unknown, continue conversationally without inventing a handoff. Unknown planning or permission state blocks persistence, not the requirements conversation.

- Use the currently observed or user-reported native control. For ChatGPT web, select the observed composer item instead of generating a CLI-style combined command.
- ChatGPT skill selection uses its available UI (such as `@`); Codex skill invocation uses `$`. Do not inject `@skill` into a mode command or infer one product's syntax for the other.
- A standalone observed `/plan` on Codex web or a non-web ChatGPT client does not prove inline prompt support. Keep the continuation separate unless this same composer demonstrates that support.
- Active Plan requires no new transition even when the composer is busy. Inactive, disabled, missing, or unknown controls do not require another requirements-question interruption.
- After approval, request only the actual exit action needed for persistence; preserve the approved draft and write scope across that transition.

## Claude Code execution host

When actually exposed, `AskUserQuestion`, `EnterPlanMode`, and `ExitPlanMode` are Claude Code controls. They do not become available merely because the output targets Claude Code. Use them according to the running host's contract. If a required transition has no tool, use its observed/documented mode selector or shortcut; do not presume every surface has the same shortcut.

A native `ExitPlanMode` approval can be the single final checkpoint when it presents the full reviewed draft and exact save-only writes. If content was already approved, invoke exit only as the remaining host action and do not ask content approval again. The host's own unavoidable permission UI is distinct from a skill-generated duplicate question.

## Cursor execution host

Use `AskQuestion` only when exposed. For a native transition that is actually needed, Cursor editor and CLI may expose different controls (for example an editor mode selector or CLI `/plan`); use current documented/client-visible controls. Do not invoke Claude tools or assume a native plan-exit tool exists. Preserve existing approval across a manual exit and complete the same save-only handoff.

## Older hosts and unavailable controls

A missing structured question, async question, native plan, or exit tool is not a reason to omit the interview or repeat approved content. Use ordinary conversation and actual permissions. While a required answer is pending, only independent authorized work continues. Silence and timeouts do not select defaults. If write state cannot be established, return the reviewed draft with persistence pending rather than attempting a write.

## Documentation pointers

Consult current primary documentation only when the relevant mechanism is unclear:

- [Codex CLI commands](https://developers.openai.com/codex/cli/slash-commands)
- [ChatGPT developer commands](https://learn.chatgpt.com/docs/developer-commands)
- [ChatGPT skills](https://learn.chatgpt.com/docs/skills-and-plugins)
- [Claude Code tools](https://code.claude.com/docs/en/tools-reference)
- [Claude Code permission modes](https://code.claude.com/docs/en/permission-modes)
- [Cursor Plan mode](https://cursor.com/docs/agent/plan-mode)
- [Cursor CLI](https://cursor.com/docs/cli/using)

These references establish documented behavior, not live proof for another client or version.

# Question Bank

Ask one high-impact question at a time when the answer can change the next question. Use a small batch only when the questions are independent and low-friction. Reuse prior answers, inspect discoverable facts, and ask only unresolved material questions. Summarize at useful milestones and continue until material aspects are resolved or explicitly accepted as non-blocking.

## Discovery

- What exact user-visible or developer-visible outcome should change?
- What problem is happening today, with one concrete example?
- Is this a bugfix, feature, refactor, migration, or repo-wide policy change?
- What is explicitly out of scope?
- What is the smallest version that would still be considered successful?

## Repo Fit

- Which files, modules, or packages are most likely involved?
- Is there an existing abstraction or pattern we should extend rather than replace?
- Which commands are the source of truth for lint, typecheck, tests, and build?
- Are there related issues, ADRs, or prior PRs?
- Does `AGENTS.md`, `CLAUDE.md`, `.claude/rules/**/*.md`, Claude Code auto memory, or another repo guide impose constraints we must preserve?
- Are there existing ADRs, specs, or named requirements that this work depends on or might need to challenge?
- Does this work introduce a durable architecture decision, or is it feature behavior under existing architecture?

## Behavior and Edge Cases

- What should happen on the happy path?
- What should happen on invalid input, empty state, loading, timeout, or partial failure?
- Are there compatibility, accessibility, localization, or performance expectations?
- What must never change as part of this work?
- What exact acceptance check would convince you this is done?

## Delivery and Rollout

- Does this require migration, backfill, config changes, or feature flags?
- Is backward compatibility required?
- Should rollout be phased, all at once, or internal-only first?
- What is the rollback strategy if behavior regresses?
- Are there high-risk areas like auth, billing, secrets, or shared contracts?
- Which repository files should document the resulting spec or ADR expectations, such as `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, or docs indexes?
- Does this change public catalog status, install behavior, trigger behavior, or promotion proof that must be reflected in repo-facing files?
- Does any result need to be distilled into `CLAUDE.md`, `.claude/rules`, or auto memory as a separate artifact, or should those stay evidence-only?

## Artifact Persistence

- If neither the request nor repository establishes a destination, propose `docs/specs/<slug>-spec.md` in the checkpoint.
- Use the existing ADR convention; ask only when its destination is materially ambiguous.
- The default specs or ADR folder is missing. Can I create `<suggested-folder>/`, or should I use a different path?
- The selected specs folder is ignored by git. Should this spec stay local-only, should I unignore that path, or should I use a tracked docs path?
- The proposed spec path is `<path>`. Should I overwrite it, choose a new slug, or update the existing spec?
- Should open question `<question>` block spec creation, or should it be recorded as a non-blocking follow-up?

## Source Challenge

- Which assumptions are inherited from an existing ADR, spec, dependency, or previous implementation?
- Which of those assumptions could plausibly be stale or wrong?
- Should any dependency, framework, API, or platform behavior be checked against current official docs before locking the spec?
- Does the repository already have a pattern that conflicts with the proposed requirement?
- Would a preceding ADR, migration note, or spec update make implementation safer?

## ADR Gate

- Does the spec change package/module boundaries, dependency direction, runtime choice, storage model, public contracts, or auth/security model?
- Is there an existing ADR that already decides this?
- If a new ADR is needed, what is the one-sentence decision?
- Is implementation blocked until the ADR is accepted?

## Final verification

Prepare the full reviewable draft before this checkpoint. Reuse answers and authority already in the conversation. Ask only the material decisions still open; the discovery and repository-fit prompts above should normally be answered from inspection.

- “Approve this version and save it to `<spec-path>` with the listed required ADR/index writes?” Include previously unapproved directory creation or overwrite in that same question.
- When saving and paths were already authorized: “Approve this version for the agreed destination?” Do not separately ask whether to save it again.
- If a required ADR remains proposed: distinguish approval to save the draft from acceptance of the architectural decision.
- If chat-only delivery was requested: verify the content when needed and deliver it in chat without offering an unwanted save.

A native plan approval may provide this checkpoint. Ask no duplicate chat question. Unambiguous “change A and save” replies authorize that bounded revision; only additional material uncertainty needs another question.

# Rollout Checklist

Use this reference when writing the validation, rollout, and rollback sections of a spec.

## Validation Plan

- List the repo's real lint, typecheck, unit, integration, e2e, and build commands; mark missing ones `unspecified` instead of inventing them.
- Include at least one concrete manual verification scenario per user-visible behavior change.
- For migrations or refactors, include a search or count check that proves the old pattern is gone or bounded.
- Name the review focus areas: regression hotspots, security-sensitive paths, and contract or schema changes.

## Phased Rollout

Phase the work when any of these apply: repo-wide scope, shared contracts, data migrations, auth/billing surfaces, or diffs too large to review safely in one pass.

For each phase, the spec should state:

- the bounded work items in the phase,
- a validation gate that must pass before the next phase starts,
- whether the phase is independently shippable or must land with others.

## Migration and Compatibility

- State whether data migration, backfill, config changes, or feature flags are required.
- State backward-compatibility expectations and any deprecation window.
- Keep a temporary compatibility shim only with an explicit removal condition.

## Rollback

- Define the rollback trigger: which failures or metrics justify reverting.
- Define the rollback procedure: what gets reverted, what can safely stay.
- Call out one-way doors such as destructive migrations or deleted contracts, and require explicit user confirmation for them.

## Monitoring

- Name what to watch during rollout: error rates, latency, auth failures, job backlogs, or the repo's existing dashboards.
- For repos without monitoring, fall back to log checks and manual verification steps and say so in the spec.

## Spec Risk Checklist

| Risk / edge case                 | Recommended mitigation                                                      |
| -------------------------------- | --------------------------------------------------------------------------- |
| Hidden migrations / rollout risk | force rollout and rollback notes for standard and deep modes                |
| Shared-contract breakage         | list affected consumers and gate the phase on contract tests                |
| Auth, billing, or secret paths   | call out explicitly, require manual verification, avoid speculative edits   |
| Too-large diffs                  | phase the work by package or module with validation gates                   |
| Partial cutover confusion        | document the default path and add a guard against reintroducing the old one |
| Silent behavior drift            | pin user-visible behavior in acceptance criteria and manual checks          |

# Source Challenge

Use this reference before finalizing a spec. The goal is to catch stale, inherited, or weak decisions without turning every spec into a full research project.

## Challenge Targets

Challenge only decisions that materially affect correctness, safety, maintainability, user behavior, or implementation strategy:

- named requirements from the user or an existing spec,
- ADR-backed assumptions,
- framework, package, API, or platform behavior,
- security, auth, billing, data migration, or shared-contract decisions,
- unusual architecture or best-practice claims,
- implementation approaches that conflict with repo conventions.

Do not re-litigate settled choices when they are still valid and low-risk.

## Source Order

Prefer sources in this order:

1. Current user answers.
2. Repo instructions such as `AGENTS.md`, `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`, `.claude/rules/**/*.md`, `~/.claude/rules/**/*.md`, and `docs/agents/`.
3. Domain language such as `CONTEXT.md`.
4. ADRs, existing specs, and plans.
5. Current source code, tests, package scripts, and CI.
6. Official docs through MCP tools when available.
7. Official web docs or primary sources when MCP tools are unavailable.
8. Secondary sources only for broad context, never as the sole basis for a risky requirement.

Treat Claude Code auto memory as a local evidence source only when the user surfaces it, `/memory` exposes it, or the requested plan depends on durable Claude context. Do not make private local memory paths part of a public spec unless the user explicitly asks.

## MCP and Web Lookup

Use MCP documentation tools or web search when:

- the spec depends on current framework, package, SDK, API, or cloud behavior,
- an existing requirement may be obsolete,
- a best-practice claim is central to the implementation,
- standards, security guidance, or compatibility constraints may have changed.

Skip external lookup when:

- repo-local source code is the actual contract,
- the decision is purely product preference,
- the change is tiny and unaffected by current external guidance,
- the user explicitly says not to browse or query external sources.

## Challenge Report

Include a short source challenge section in the final output:

```md
## Source challenge

- Repo evidence checked:
- ADRs/specs checked:
- External docs checked:
- Requirements revised:
- Requirements preserved:
- Preceding ADR/spec work needed:
- ADR gate result:
- Skipped checks and why:
```

Use concise findings. If all checks support the existing plan, say that directly.

## Preceding Decisions

If the challenge shows that a prerequisite decision is missing or stale:

1. Do not silently encode the disputed assumption into the implementation spec.
2. Propose a preceding ADR, spec revision, or explicit maintainer decision.
3. Mark implementation as blocked or phased until that decision is resolved.
4. Keep the final spec honest about what is decided and what is not.

# Spec Rubric

Use this before finalizing the implementation spec.

## Mode Selection

| Mode       | Use when                                                                         | Required depth                                        |
| ---------- | -------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `compact`  | one-file or tightly scoped feature/bugfix with low ambiguity                     | enough to implement safely in one sitting             |
| `standard` | default for most features, bugfixes, refactors, migrations                       | explicit requirements, file plan, validation, risks   |
| `deep`     | repo-wide refactor, architecture change, migration, multi-team or phased rollout | requirements, design, phased tasks, rollout, rollback |

## Required Sections

| Section                            | Compact   | Standard | Deep     |
| ---------------------------------- | --------- | -------- | -------- |
| Frontmatter                        | required  | required | required |
| Goal                               | required  | required | required |
| Scope                              | required  | required | required |
| Non-goals                          | optional  | required | required |
| Repo context                       | required  | required | required |
| Assumptions / open questions       | required  | required | required |
| Requirements / acceptance criteria | required  | required | required |
| ADR gate                           | required  | required | required |
| Design notes                       | optional  | required | required |
| Task breakdown                     | light     | required | required |
| Validation commands                | required  | required | required |
| Source challenge                   | required  | required | required |
| Risks / rollout                    | optional  | required | required |
| Artifact path / persistence        | path only | required | required |
| Done when                          | required  | required | required |

## Acceptance criteria bar

- Specific, testable requirements and bounded scope; actual repository facts and commands where known.
- Important assumptions challenged against repository evidence and current primary sources when relevant; skipped checks explained.
- Durable decisions in ADRs, with proposed persistence and acceptance distinguished; feature details stay in the spec.
- Complete reviewable content prepared before one approval covering the revision and its concrete writes. Reuse prior answers and exact authority.
- Planning and permissions capability-gated independently; missing controls allow conversation, never unproven writes.
- Delivery matches the request: saved artifacts read back or explicit chat-only output fulfilled. Pending Plan exit or blocked requested save is not success.
- Risky changes include rollback. The Claude Code execution prompt is usable without another avoidable interview.

## Final self-check

- Are scope, non-goals, acceptance criteria, commands, risks and unknowns concrete?
- Did the interview resolve material choices without asking again about facts or answers already available?
- Does the reviewed version include the final spec, required ADR content and exact paths/write actions?
- Is approval of that unchanged version reused, including across a native Plan exit?
- Were only affected changes reconfirmed after material content, destination, write-scope or target-state drift?
- Were native tools used only when exposed and permitted, without blocking permissible reads on a mode switch?
- Was silence, timeout or a preselected answer kept distinct from consent?
- Were writes deferred during native Plan or unknown mode/permission state?
- Are content approval and actual persistence recorded separately, once each?
- Did requested persistence succeed and get read back, or did explicit chat-only delivery complete?
- Are required ADR acceptance gates visible and minimal required index writes included?
- Did the interviewer finish save-only work without implementing features or unrelated docs, preserving any separately authorized outer workflow?

# Interview and approval lifecycle

Use this reference for the substantive interview and final delivery. The target runtime determines evidence and the execution prompt; the current execution host determines available tools, planning controls, and permissions.

## Planning and permission evidence

Inspect current host context and exposed controls without blocking useful read-only discovery. Record `Planning capability:` as active, available but inactive, unavailable, explicitly declined, or indeterminate, with the evidence. Record `Read-only enforcement:` independently from runtime permissions; a Plan label or a mode command is not proof of enforcement. Report these when they affect the next action, and update them when the state changes.

- Respect active or explicitly requested native Plan mode. Recommend it for substantial open work, but do not require a manual transition before permissible reads or conversation.
- Missing, inactive, busy, older, or unknown controls permit the same conversational interview with a behavioral no-write gate. An indeterminate state is not proof of unavailability and never permits writes. Do not make the user enumerate UI controls merely to answer an unrelated requirements question.
- An explicit refusal is separate evidence: record it and do not recommend Plan again. It does not exit an already active mode or waive write permissions.
- Use only tools actually exposed by the execution host, and follow their restrictions. Structured or asynchronous questions are optional capabilities, not prerequisites. With no suitable tool, ask in ordinary conversation.
- While a material answer is pending, continue only independent authorized work. Silence, a timeout, or a preselected option is not an answer or approval. Keep the dependent decision pending.
- Do not test permissions by writing or silently change host configuration. During the interview, prohibit repository, workspace, and external mutations; a native host-managed plan artifact is allowed only if the host explicitly permits it. Never persist repository artifacts while native Plan is active.

## Interview

1. Classify depth as `compact`, `standard`, or `deep` using [spec-rubric.md](spec-rubric.md). This is one end-to-end workflow; a clear request selects it without another workflow menu. A bare invocation needs the missing task, not a review/save variant choice.
2. Inspect the relevant repository and conversation first. Reuse prior answers and authority; resolve discoverable facts from source. Determine delivery intent and candidate paths using [artifact-destinations.md](artifact-destinations.md). Raise consequential public/private or overwrite ambiguity early, or bundle it into the final checkpoint.
3. Ask only unresolved material questions. Keep dependent decisions in real back-and-forth; batch a few independent choices when useful. Summarize changed understanding at useful milestones, not mechanically after every answer. Use [question-bank.md](question-bank.md) as prompts to consider, not a questionnaire to exhaust.
4. Challenge important assumptions against repository evidence and current primary sources using [source-challenge.md](source-challenge.md). Run [adr-gate.md](adr-gate.md); a proposed ADR may be saved without being accepted, and dependent implementation stays blocked until its decision is accepted.
5. Prepare the complete reviewable spec and any required ADR/index content before requesting approval. Use the matching template in `../assets/`, testable acceptance criteria, concrete validation and explicit unresolved facts. Identify the revision in conversation so the approval applies to that content. Do not ask approval of a summary and then invent the final artifact.

## One final checkpoint

Present the full draft or a reviewable artifact with a concise summary of scope, assumptions, risks, validation, ADR status, delivery and concrete paths. List any directory creation, overwrite, ADR status change and minimal required index update. Reuse already granted authority rather than asking for it again. Ask positively, for example: **Approve this version and save it to `<spec-path>` with the listed artifact writes?** If saving and the destination were already authorized, only the content approval remains.

A native plan approval may be this same checkpoint when it presents and approves the content and exact write scope. Do not add a second chat approval before or after it. A mode toggle alone is not content approval. Keep content verification, write authorization, host state, and actual persistence distinct.

| Existing evidence or change                                  | Next action                                                                                                                             |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Exact draft and listed writes already approved               | Reuse that approval; save when the host permits it.                                                                                     |
| Approval given while Plan remains active                     | Retain approval; request only the required host exit, with persistence pending.                                                         |
| Exit confirmed and approval unchanged                        | Perform the save-only handoff without another verification question.                                                                    |
| Earlier directory creation, overwrite, or save authorization | Carry it into the checkpoint; do not ask again for the same target state.                                                               |
| “Change A and save” identifies an unambiguous bounded edit   | Apply that revision and save within existing authority; do not automatically add a new approval round.                                  |
| Material content, path, write scope, or target state changed | Show the affected difference and confirm only that delta before the affected write.                                                     |
| Draft or approval lost after context loss                    | Recover the reviewed content and authority from available evidence; ask only for what cannot be recovered.                              |
| Explicit chat-only delivery                                  | Deliver the full approved spec and execution prompt in chat; complete that requested delivery with `Persistence status: not requested`. |
| Requested save is blocked or denied                          | Preserve approval, report the specific blocker and unsaved paths, and return save-ready content; persistence remains incomplete.        |

A “yes” to a proposal to save an ADR as `Proposed` does not accept its architecture decision. ADR acceptance must explicitly cover the reviewed decision. Prior acceptance of that exact decision remains valid.

## Save-only handoff

If Plan is active, report `Persistence status: pending Plan-mode exit`. Use the current host's plan-exit control if available and permitted; otherwise state the observed/documented manual exit action. Request only the host action still needed. A suitable continuation is:

```text
Exit Plan mode, then persist the already approved spec to <spec-path>, the listed required ADR artifacts and minimal convention-required ADR index update. Reuse the existing approval. Validate and report the saved paths and emit the target-runtime execution prompt. Do not implement the feature in this save-only handoff.
```

After actual exit, recheck the destination state and write permissions. Unknown mode or permission state means no writes; resolve only the uncertainty that blocks the save. Save only the approved spec, required ADR and minimal required ADR index entry. Read back the artifacts, report actual results, run the final rubric, and emit the target-runtime execution prompt. A partial write failure must report which artifacts were saved and which remain pending; do not claim atomic success.

The interviewer does not implement features or unrelated documentation changes. Its save-only task ends here. An outer workflow may resume separately authorized implementation after this handoff; the spec approval itself never grants that authority.

## Delivery and completion

Report delivery first: saved paths, requested chat-only delivery, or pending/blocked persistence. Follow with material assumptions, source challenge and ADR result, the execution prompt, validation and remaining risks. Avoid repeating the full saved artifacts unless requested. For chat-only delivery or a blocked save, include the complete draft; distinguish a draft awaiting approval from an approved result.

Completion means the requested delivery succeeded: either saved and read back, or explicitly requested chat-only output delivered. Pending Plan exit or a failed requested save is not completion. Record verification once; persistence records actual results separately. Required ADR acceptance remains an independent implementation gate even when delivery is complete.

---
name: claude-spec-interviewer
description: Turn ambiguous coding requests into verified Claude Code implementation specs. Use when the user wants requirements, an implementation plan, or a spec before coding; include source checks, needed ADRs, and agreed delivery. Do not use for already specified direct implementation or memory cleanup.
license: Apache-2.0
compatibility: Targets Claude Code evidence and execution prompts across Agent Skills hosts. Use the current execution host's available controls and permissions, with conversational support for older hosts.
metadata:
  author: stark-ai-de
  category: claude-operations
  version: "0.3.0"
---

# Claude Spec Interviewer

## Goal

Produce a user-verified implementation spec with bounded scope, testable acceptance criteria, source-backed decisions, validation, and any required ADRs. Deliver it to the agreed repository path, or in chat when explicitly requested. One approval covers the unchanged result and its concrete authorized writes.

This is one end-to-end workflow. A clear request selects it; do not invent review/save variants or add a workflow-selection checkpoint. For a bare invocation, ask for the task to specify.

## When to use

- The user has a rough idea but not a production-ready implementation spec.
- The task spans multiple files or concerns, or requires tradeoff decisions.
- The request needs acceptance criteria, validation commands, rollout notes, or risk handling.
- The user wants a reusable written artifact before implementation begins.
- The user invokes `/claude-spec-interviewer` or asks Claude Code to plan before coding.
- Requirements, feature shape, ADR assumptions, or the implementation approach should be challenged against repo reality and current external sources before coding.

## When not to use

- The user already provided a complete implementation spec with files, constraints, tests, and acceptance criteria.
- The task is a tiny one-file edit without meaningful ambiguity.
- The user wants brainstorming only and no concrete implementation artifact.
- The user only wants a Claude Code rule, command, or other prompt-scope file authored, not an implementation spec.
- The task is primarily a policy, legal, or business-decision document.
- The user asks to audit or clean up Claude Code memory, Codex memory, or Cursor rules state; use the matching memory or rules skill instead.

## Inputs to inspect

- The current user request and any follow-up answers.
- Relevant `AGENTS.md`, `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`, `.claude/rules/**/*.md`, `~/.claude/rules/**/*.md`, `README.md`, issue descriptions, ADRs, repo docs, and `docs/agents/` files.
- Existing specs, plans, requirements, and PRDs the user wants preserved or challenged.
- File layout, naming conventions, scripts, package manager, lint/test/type-check commands, and CI expectations.
- Current framework, library, API, or platform documentation through available MCP tools or web search when a decision depends on up-to-date behavior.
- Error messages, screenshots, logs, PR feedback, or example files the user supplied.
- Claude Code project or personal skill folders such as `.claude/skills/` and `~/.claude/skills/` only when the spec depends on local Claude Code skill behavior.
- Claude Code auto-memory evidence only when it is surfaced by the user, available through `/memory`, or materially relevant to the requested implementation plan.

## Workflow

Follow [workflow-details.md](references/workflow-details.md) for the shared interview, approval and delivery lifecycle. Use [host-adapters.md](references/host-adapters.md) only when a host control or transition matters.

1. Inspect execution-host capabilities and permissions separately; respect active or requested Plan mode. Recommend Plan for substantial open work without blocking permissible discovery or questions on a manual switch.
2. Inspect relevant repository context and prior answers. Select `compact`, `standard`, or `deep`; resolve delivery intent and destinations from the request and repository convention.
3. Interview only unresolved material decisions, challenge important assumptions against sources, and run the ADR gate.
4. Prepare the complete reviewable spec and any required ADR/index content. Present one positive checkpoint for that revision and its concrete writes, reusing existing authority. A native plan approval can serve as this checkpoint.
5. Preserve approval across any required Plan exit. Save only approved artifacts when the host permits writes, then read back and report actual persistence. Explicit chat-only delivery completes without a save.
6. Emit the Claude Code execution prompt and run the rubric. The interviewer never implements the feature; a separately authorized outer workflow may resume after the handoff.

## Safety rules

- Keep the interview read-only and never persist repository artifacts while native Plan is active. Unknown mode or write permission state does not permit writes.
- Reuse prior answers and approval of unchanged content and writes. Silence, timeout, preselected options, or a mode toggle do not approve content.
- Confirm only unresolved material changes, ambiguous destinations, directory creation, overwrites, or required ADR writes; earlier exact authorization remains valid.
- Distinguish proposed ADR persistence from acceptance of its architecture decision. Block dependent implementation until required acceptance.
- Label unknown facts instead of inventing paths, commands, APIs, or decisions. Avoid secrets and private identifiers in artifacts.
- Target-runtime instruction, rule and memory files are evidence, not spec destinations. Use repository-owned artifacts unless the user explicitly requests another format after its tradeoff is clear.
- Preserve user scope. Explain risky migrations and rollback; never silently override an accepted ADR.

## References

Read only the reference needed for the current step:

- [workflow-details.md](references/workflow-details.md): interview, single checkpoint, save-only handoff and completion.
- [host-adapters.md](references/host-adapters.md): execution-host controls and capability evidence.
- [question-bank.md](references/question-bank.md), [spec-rubric.md](references/spec-rubric.md), and [source-challenge.md](references/source-challenge.md): unresolved questions, depth, final self-check and source challenge.
- [artifact-destinations.md](references/artifact-destinations.md), [adr-gate.md](references/adr-gate.md), and [rollout-checklist.md](references/rollout-checklist.md): destinations, durable decisions and risky delivery.
- Matching `assets/spec-template.*.md`, bundled example specs and [execution prompt](assets/claude-execution-prompt.md): output formats.

## Scripts

No bundled scripts.

## Output format

Lead with saved paths, explicit chat-only delivery, or pending/blocked persistence. Include the verification result, material assumptions, source challenge, ADR status, validation, risks, and the Claude Code execution prompt. Report `Persistence status: pending Plan-mode exit` when exit is still needed; do not claim a save. Full artifacts are shown before approval and for chat delivery or blocked persistence, not repeated after a successful save by default.

## Completion criteria

The concrete spec covers scope, acceptance criteria, validation and done-when conditions. The user approved its current content and required writes once. Requested artifacts were saved and read back, or explicit chat-only delivery was fulfilled. Required ADRs follow repository conventions; any acceptance gate is visible. Verification and persistence are separate records. Save-only finalization never implements the feature.

## Failure modes

- Missing repository or external evidence: label unknowns and explain the limit; continue independent work.
- Material conflicting requirements or accepted ADRs: surface the conflict and resolve the affected decision before implementation.
- Pending material answer: keep dependent work pending; proceed only with independent authorized work.
- Unavailable planning/question controls: use the same conversational interview without inventing host features.
- Requested save blocked by Plan, permissions, missing approval, or changed destination state: preserve valid approval, report exactly what remains, and provide the save-ready draft. Do not call pending persistence complete.