doc-first-interrogation

name

doc-first-interrogation

description

Run a documentation-first plus interrogation-first delivery workflow. Use when a request is underspecified, when an agent should clarify requirements before coding, when canonical planning docs such as `PRD.md`, `APP_FLOW.md`, `TECH_STACK.md`, `FRONTEND_GUIDELINES.md`, `BACKEND_STRUCTURE.md`, and `IMPLEMENTATION_PLAN.md` need to be created or refreshed, or when implementation should be driven from written specs instead of a raw chat prompt across Codex, Claude Code, or OpenCode-style agent setups.

Doc-First Interrogation

Turn a vague request into a documented execution loop: interrogate until critical assumptions are surfaced, write or refresh the steering and feature docs, then implement against those docs instead of the raw prompt.

Quick Start

1. Interrogate first if the request leaves product intent, constraints, edge cases, rollout, or verification unclear. Use references/interrogation-checklist.md.
2. Bootstrap missing docs with:

python /path/to/doc-first-interrogation/scripts/bootstrap_spec_docs.py --feature "Feature name"

3. Update the generated or existing docs before coding.
4. Treat the docs as the source of truth while implementing.
5. Record execution notes in progress.md and promote durable lessons to lessons.md.

Canonical File Set

• PRD.md: product intent, user problems, scope, and success metrics.
• APP_FLOW.md: key user journeys, screens, states, and transitions.
• TECH_STACK.md: stack, integrations, constraints, and technical decisions.
• FRONTEND_GUIDELINES.md: UI patterns, interaction rules, accessibility, and design constraints.
• BACKEND_STRUCTURE.md: services, modules, data flows, boundaries, and contracts.
• IMPLEMENTATION_PLAN.md: milestone plan, task sequence, dependencies, and verification checkpoints.
• AGENTS.md or CLAUDE.md: agent operating instructions for the local repository.
• progress.md: short-term execution log, blockers, decisions, and next steps.
• lessons.md: durable learnings that should change future behavior.

Agent Portability

• This skill is published as generated variants for Codex, Claude Code, and OpenCode.
• The workflow itself is agent-agnostic. The same SKILL.md, references/, and scripts/ content can be reused across those runtimes.
• The Codex variant adds agents/openai.yaml; Claude Code and OpenCode use the same core skill content without that file.
• Keep the canonical document set tool-agnostic so the same project docs survive agent changes.
• Read references/workflow-map.md for file responsibilities and install surfaces.

Core Workflow

1. Interrogate Until the Problem Is Sharp

• Ask high-leverage questions first: outcome, users, scope, constraints, failure modes, and verification.
• Keep questioning until you can write requirements without inventing hidden assumptions.
• If the user is unavailable, write explicit assumptions and mark them as provisional.
• Do not start implementation while critical unknowns remain unresolved.

2. Refresh the Steering Docs

• Read the current AGENTS.md or CLAUDE.md and any existing planning docs before drafting new ones.
• Update existing docs in place when they are stale; do not create duplicate sources of truth.
• Keep the canonical planning docs stable and reusable across features.
• Capture cross-cutting rules or enduring heuristics in lessons.md, not in a one-off feature spec.

3. Write the Feature Spec Pack

• Use IMPLEMENTATION_PLAN.md plus progress.md as the execution pack.
• Use written planning docs to lock behavior, architecture, and execution order before coding.
• Start progress.md before coding and update it after each meaningful step, decision, or blocker.

4. Implement From the Docs

• Re-check the docs before each substantial code change.
• If reality diverges from the spec, update the docs first or in the same change set.
• Use progress.md as the short-term working memory for what changed, what failed, and what is next.

5. Close the Loop

• Verify the implementation against the planning docs and the verification plan in IMPLEMENTATION_PLAN.md.
• Move durable fixes, pitfalls, and heuristics into lessons.md.
• Keep progress.md concise but factual so another agent can resume without re-discovery.

Operating Rules

• Prefer clarifying questions over silent guessing.
• Prefer explicit assumptions over implicit assumptions.
• Prefer updating existing docs over creating parallel docs with new names.
• Prefer feature-local notes in progress.md; promote only reusable insights to lessons.md.
• When the user asks for implementation immediately, still do the minimum interrogation and doc refresh needed to avoid avoidable churn.

References

• Use references/interrogation-checklist.md for the questioning rubric and stop condition.
• Use references/workflow-map.md for canonical file responsibilities and portability notes.