Turn decisions into durable documents with ak:interview-docs

Use ak:interview-docs when the user's knowledge, taste, and explicit decisions should become a durable project document. The Skill conducts a guided interview and patches the evolving document after each answer instead of inventing a position, extracting one from code, or waiting until the end to save the work.

Choose ak:interview-docs for user-authored decisions

Use ak:interview-docs when

• You want to articulate project vision or README direction in your own words.
• You have made an architectural decision and want a short, reviewable ADR.
• You want to develop principles, strategy, a review, or a framework through a focused question-and-answer process.
• You want each answer persisted before the interview continues so progress is recoverable and easy to inspect.

Choose another workflow when

• You want the assistant to propose options or help decide. Use ak:brainstorm, then return after you choose.
• Documentation should be derived from repository behavior, APIs, or source code. Use ak:docs.
• You already have a complete document and only need editing, translation, or formatting. Use the relevant documentation or artifact workflow.
• You want an unordered list silently converted into priorities, phases, or a roadmap. This Skill must ask before assigning order.

Prepare the interview boundary

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Choose a broad vision interview or one structured document. If the request fits both, expect one concise mode-selection question.
• Provide the project root and, for structured-document mode, the exact target path or topic. Preserve unrelated changes in nearby documents.
• Decide whether the output belongs in README.md, a short numbered ADR, or a named document. State any repository-specific location and format rules.
• Remove secrets, credentials, private personal data, and content that should not become durable project history.

The declared input is <vision | document-path | topic>. It is an intent hint, not a fixed parser. Name the mode, target, audience, scope, and topics you do not want the interview to cover.

Run an interview with a concrete target

/ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

/ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

$ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

A strong request defines whose thinking is being captured, the target document, the intended reader, the desired level of detail, protected sections, whether new files are allowed, and the phrase that ends the interview.

Choose the interview mode

Vision mode keeps the README focused on vision. Each ADR is short and contains Status, Context, Decision, and Consequences; it records only a decision you have explicitly made. Structured-document mode works on one document such as principles, strategy, a review, or a framework and preserves your wording and subsequent edits.

Observe the interview stages

1. The Skill reads the existing context. Vision mode reads the README and ADR directory. Structured-document mode reads the target and nearby docs.
2. It confirms the mode and target. Only a materially ambiguous request should require a preliminary mode question.
3. It creates the smallest safe structure. A missing structured document receives a minimal skeleton once; existing content is preserved rather than replaced wholesale.
4. It asks according to the selected rhythm. Vision mode uses a varied batch of five by default. Structured-document mode asks exactly one focused, open-ended question.
5. You answer or correct the premise. Your answer supplies the document's substance. An unordered list remains unordered unless you approve a rank, sequence, or priority.
6. The Skill re-reads and patches immediately. It applies the answer to the affected document before processing the next answer.
7. The loop continues until you end it. The closing report identifies files, captured decisions, open sections, and anything deliberately excluded.

Keep authorship and approval with the user

• Do not record secrets, credentials, access tokens, private personal data, or sensitive operational details in durable docs.
• Preserve user wording and later manual edits. Patch the relevant section; do not replace an existing document wholesale or add speculative sections.
• Ask before converting a list into an ordered sequence, priority, score, timeline, or recommendation.
• Keep facts, opinions, hypotheses, and decisions distinguishable. Record uncertainty when the user expresses it.
• Do not commit, push, publish, or distribute the document unless a separate authorized workflow performs that action.

Verify the document and evidence

A complete interview result should include:

• The exact target files created or patched and the section affected by each accepted answer.
• A README limited to project vision, or numbered ADRs with Status, Context, Decision, and Consequences for decisions the user actually made.
• For a structured document, a coherent minimal structure whose claims and language trace back to the interview rather than source-code inference.
• Unordered items left unordered unless explicit ordering approval is recorded.
• Open questions, deferred sections, contradictions, and user corrections that still need resolution.
• A final diff review showing existing content and unrelated work were preserved.

The pinned stable and beta releases contain the same Skill file. The bundle has no templates, scripts, or automated tests for the interview loop; output quality depends on the user's answers, the existing documents, and the runtime's ability to pause, re-read, and patch reliably.

Troubleshoot and interpret limits

Use ak:brainstorm before the interview when you need options, or ak:docs when the repository itself is the source of truth.