Tempting shortcut
The user listed five ideas; order them by importance.
Do this instead
A user list is unordered unless they approve rank or priority.
Ctrl K
Quick Ref / Command
Marketing Kit
/ak:interview-docs
Interview-Driven Docs
Turn the user’s own vision, decisions, and wording into durable README, ADR, principles, strategy, review, or framework documents through a guided interview.
01
Select mode
02
Ask if ambiguous
03
Read nearby docs
04
Interview from user
Rule 01
The document should preserve the user’s knowledge, taste, and decisions.
Rule 02
Ask before ranking, sequencing, or prioritizing user-provided material.
Rule 03
Use ak-brainstorm for AI proposals and ak-docs for code-derived documentation.
Execution Map
Core lanes from input to output, aligned with the command's real execution path.
01
Start
Input, scope, route
- 1 Select mode Choose vision mode for project vision, README direction, and ADR decisions; choose structured-doc mode for one user-authored principles, strategy, review, or framework document.
- 2 Ask if ambiguous If both modes fit, ask one concise question before writing.
02
Work
Agent / skill execution
- 3 Read nearby docs In vision mode, read README.md and docs/adr first; in structured mode, read nearby documents and create only a minimal skeleton once.
- 4 Interview from user Ask five high-variety questions in vision mode, or exactly one specific open question at a time in structured-doc mode.
03
Verify
Gate, review, validation
- 5 Patch after each answer After every answer, re-read the affected document or section and patch the user’s words before asking the next question.
- 6 Preserve decisions Keep README to vision and record explicit architectural decisions in short numbered ADRs with Status, Context, Decision, and Consequences.
04
Close
Report, handoff, artifact
- 7 Respect unordered lists Treat a user-provided list as unordered until the user explicitly approves rank, sequence, or priority.
- 8 Stop speculation Never invent content, overwrite existing docs, add speculative sections, or use ADRs to make unapproved architecture decisions.
Don't skip the required step
Each item contrasts a tempting shortcut with the required approach.
Tempting shortcut
The code reveals the architecture; write an ADR.
Do this instead
ADR records only decisions the user explicitly made.
Sample Prompt
Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.
Vision interview Recommended
/ak:interview-docs project vision for the README and first ADRs- Use when:
- The user’s vision and decisions should shape README/ADR content.
- Expected:
- Reads existing docs, asks high-variety questions, and patches user wording after each answer.
Structured document
/ak:interview-docs docs/principles.md- Use when:
- One durable document should be built through one-question-at-a-time interviewing.
- Expected:
- Creates a minimal skeleton if needed, asks exactly one open question, and preserves edits.
Marketing principles doc
/ak:interview-docs write a marketing principles doc from our decisions- Use when:
- The document must come from the user's answers, not invented strategy copy.
- Expected:
- Asks interview questions one at a time, then writes a principles doc in the user's wording without inventing strategy.
Handled Scope
- Guided documentation interviews
- README vision updates
- ADR capture
- Principles and strategy documents
- User-wording preservation
Artifacts Produced
Interview-docs output
Pattern
Updated README, ADR, or target document with user-sourced wording and explicit decisions only. The process continues answer by answer until the user ends the interview.