Turn stakeholder decisions into documents with ak:interview-docs

Use ak:interview-docs when the durable artifact should come from a person's knowledge, taste, and explicit decisions. The Skill asks questions, waits for answers, and patches those answers into the target as the interview progresses; it does not invent missing content or infer decisions from code.

Choose an interview when the user is the source

Use ak:interview-docs when

• A founder or stakeholder needs to articulate project vision or README direction.
• An approved architectural decision needs a short ADR.
• You want to author principles, strategy, a review, or a framework one focused question at a time.
• A document brief is incomplete because key judgment still lives with a person.

Choose another workflow when

• Documentation should be derived from repository evidence. Use ak:docs.
• You want the assistant to propose and compare options. Use ak:brainstorm.
• You need interview findings synthesized from an existing transcript rather than a live guided interview. Give that bounded synthesis task to a suitable research or writing workflow.

Prepare the mode, target, and authority

Choose vision mode for project vision, README direction, and ADR decisions. Choose structured-doc mode for one user-authored document such as principles, strategy, a review, or a framework. If both fit, the Skill asks one concise question before writing.

Name the topic or document path, state who will review it, and identify private or sensitive material that must stay out. Run from the project containing the existing documents. Vision mode reads README.md and docs/adr; structured-doc mode reads nearby documents and the target section.

Start the interview

/ak:interview-docs ./docs/campaign-principles.md Interview me to capture the principles for approving campaign claims. Preserve my wording, ask one open question at a time, and do not publish

/ak:interview-docs ./docs/campaign-principles.md Interview me to capture the principles for approving campaign claims. Preserve my wording, ask one open question at a time, and do not publish

$ak:interview-docs ./docs/campaign-principles.md Interview me to capture the principles for approving campaign claims. Preserve my wording, ask one open question at a time, and do not publish

The argument can be a vision, a document path, or a topic. It is not a batch generation flag: the workflow remains interactive and waits for user answers.

Understand the two interview stages

Vision mode

1. Read README.md and the existing docs/adr directory.
2. Ask a batch of five varied questions unless you request another number or a focused area.
3. After each answer, re-read the affected document and patch the user's words into README.md or an ADR before processing the next answer.
4. Keep README.md focused on vision. Put an explicitly approved decision in a short numbered ADR with Status, Context, Decision, and Consequences.
5. Continue until the user ends the interview.

Structured-doc mode

1. Read nearby documents and create one minimal skeleton.
2. Ask exactly one specific, open question and wait.
3. Re-read the target section and patch the answer before asking the next question.
4. Preserve user wording and edits. Never overwrite an existing document or add speculative sections.

Keep authorship and approval with the user

Do not write secrets, credentials, personal data, or confidential interview material into project docs. Local file edits do not authorize publishing, contacting participants, changing live accounts, or sharing the document with an external provider.

Verify the document and interview evidence

A complete result should show:

• the selected mode and target document;
• the questions asked and the user's decisions captured in the current session;
• a focused diff preserving user wording and existing edits;
• no invented rank, decision, evidence, or speculative section; and
• any unanswered question or publication step still requiring approval.

Vision-mode output is limited to README.md direction and short numbered ADRs under the project's existing docs/adr route. Structured-doc output stays in the named document. Review the diff after every material answer, not only at the end.

Troubleshoot and understand limits

The Skill cannot recover intent you do not state, validate a user's decision against external evidence by itself, or guarantee a document is ready to publish. Continue with ak:docs when the interview artifact later needs to be reconciled with project evidence.

See the Marketing Kit overview and Projects, artifacts, and checkpoints.