Write a PRD or ADR

Planning documents create accountability. A PRD ensures everyone agrees on what to build. An ADR ensures everyone understands why a technical decision was made.

In kill9, you do not write these documents yourself. You direct an agent to write them, then review and refine the result. The agent does the drafting. You do the deciding.

PRD — Product Requirements Document

A PRD defines what a feature should do, what success looks like, and what is out of scope. kpm (the product manager agent) writes it. You review it before implementation starts.

When to produce a PRD

Produce a PRD for any feature that affects user-facing behavior, has multiple stakeholders, or requires coordination between agents. If the feature is trivial — a one-line fix or a simple configuration change — skip the PRD.

How the interaction works

Step 1 — Create the initiative.

In Plan (Mod+3), create a feature initiative. Describe what you want in plain language. The initiative description is the raw material kpm will work from.

Step 2 — Open Docs and create a PRD document.

In Docs (Mod+4), create a new document of type PRD. Link it to your initiative.

Step 3 — Ask kpm to draft it.

In the agent chat pane (right side), tell kpm what you need:

Use kpm to draft a PRD for adding dark mode. Include user preferences, system detection, and persistence across sessions.

Step 4 — Answer kpm's questions.

kpm does not produce a full PRD in one shot. It reads your initiative description, mirrors its understanding back to you, and asks structured questions one at a time.

For example:

kpm: I think the toggle should be in the Settings page. Confirm?
You: Yes, but also add a keyboard shortcut.

Each requirement is closed individually — proposed, confirmed or corrected, then moved on from. This prevents the common failure of building the wrong thing because requirements were misunderstood early.

kpm may delegate specific questions to other agents:

• karch for technical feasibility
• kui for UI implications
• kresearch for competitor analysis or external data

Step 5 — Review the draft.

Once all requirements are closed, kpm produces a draft. It appears in the editor (center pane). Read it carefully.

What to check:

• Are the requirements measurable? "Returns 401 on invalid token" not "handles auth correctly"
• Is the scope clear? What is in scope and what is explicitly out of scope
• Are the acceptance criteria verifiable? A tester should know exactly how to check each one

Step 6 — Edit and refine.

Edit the draft directly in the editor. Add specifics, remove assumptions, clarify edge cases. The agent draft is a starting point, not a finished product.

Step 7 — Request review.

Switch to the Comments tab and tag team members. They add comments on specific lines. You see their feedback inline in the editor.

Step 8 — Approve.

Address all feedback, resolve comment threads, then click Approve in the review bar. The PRD is now locked and the initiative's design gate is satisfied.

What a good PRD contains

• Summary — one paragraph describing the feature
• Goals — what this feature achieves
• Non-goals — what is explicitly out of scope
• Use cases — specific scenarios with user actions
• Requirements — numbered requirements with acceptance criteria
• Open questions — anything that needs resolution before implementation

ADR — Architecture Decision Record

An ADR documents a technical decision, the alternatives considered, and the trade-offs. karch (the architect agent) writes it. You review it before implementation starts.

When to produce an ADR

Produce an ADR for any significant technical decision: choosing a technology, changing a pattern, or introducing a new abstraction. If the decision is obvious or reversible, skip the ADR.

How the interaction works

Step 1 — Approve the PRD first.

karch reads the approved PRD before proposing any architecture. No PRD, no ADR.

Step 2 — Ask karch to draft it.

In the agent chat pane:

Use karch to write an ADR for the dark mode implementation. Compare CSS variables vs theme provider approaches.

Step 3 — Review the draft.

karch produces an ADR with specific depth:

• Component boundaries and data flow
• File names and module references
• API shapes and type definitions
• How the change fits existing code patterns
• Each architecture decision mapped to a PRD requirement ID

This is not a high-level sketch. It is implementation-ready architecture. A developer should be able to read the ADR and build the feature without re-deriving decisions.

Step 4 — Edit and refine.

Check that the ADR names specific files, cites existing patterns, and explains trade-offs. If it says "use a context provider" but does not say which file to create, ask karch to be more specific.

Step 5 — Request review and approve.

Same process as the PRD — comments in the Comments tab, address feedback, click Approve.

What a good ADR contains

• Context — what problem are we solving
• Decision — what we decided
• Consequences — what this means for the codebase
• Alternatives — what else we considered and why we rejected them

The review process

Both PRDs and ADRs go through review before approval. The process is the same for both:

1. The agent produces a draft
2. You edit and refine it
3. Team members add comments on specific lines in the Comments tab
4. You address the comments and resolve the threads
5. When all feedback is addressed, you click Approve

An approved PRD satisfies the design gate in the feature workflow. An approved ADR is referenced by stories so developers do not re-derive decisions.

Your role vs the agent's role

The agent does the writing. You do the deciding.

Related pages

• Documents — the three-pane document workspace
• Plan a feature — where PRDs and ADRs fit in the workflow
• Agents — kpm and karch