Stop Rewriting Prompts: product-os Standardizes Requirement Docs in 5 Steps

Preface

The author describes their current AI-assisted development flow: operations or product hands over requirement docs, dev docs, interaction HTML, and UI designs. They manually read everything, write custom prompts for the Agent, use prd-three-layer-template to generate dev-slim.md, then code against that. For iterations they add a prd-iterate step; when materials are poor they rewrite requirements with pm-skills and create interaction pages with html-design-prototypes before generating dev-slim.

The process works but has two repeating problems: every requirement triggers a rewrite of the same prompts, and the three routes (organize, rebuild, iterate) produce differently formatted requirement docs, forcing realignment each time.

Core idea: Fix the "requirement materials → delivery requirement document" segment. Unified entry, unified exit, route chosen by written rules — not by today's ad-hoc prompts.

Premise

AI can draft PRDs, prototypes, and specs quickly. Drafts are cheap; value lies in three things: scope clarity and change traceability, write-back of decisions, and ownership after launch. Fixing the process isn't about producing more files — it's about making those three things leave consistent traces on every requirement.

This article covers only the product side: from raw materials to a delivery-ready requirement doc. Generating dev-slim and coding are downstream, briefly noted at the end. The flow suits long-running multi-requirement contexts with frequent changes and eventual handoff to coding Agents. Trivial copy edits or clear bugs skip the flow.

Current Process: Where Repetition Lives

A table breaks down five stages and their issues:

Read materials: manual read each time, no log → next session doesn't know what was seen.

Write prompts: rewrite per requirement → same problems re-solved, quality varies daily.

Choose route: gut feel for organize/rebuild/iterate → no record of why.

Output requirement doc: three routes, three formats → downstream realigns every time.

Requirement changes: edit doc or full rerun → what changed and why is lost.

The real repetition: rewritten prompts and inconsistent output formats . The former can become files; the latter can become templates.

Fixed Flow: One Entry, Five Steps, One Exit

The diagram enforces three contracts:

Unified entry: all changes enter via step 01 Intake; no bypassing to edit delivery doc directly.

Unified exit: all three routes end at the same delivery/PRD.md template.

Rule-based branching: route A/B/C decided by rules in triage.md; rationale recorded.

product-os Directory Structure

product-os/  AGENTS.md          # rules + flow entry  playbook/          # fixed commands replacing hand-written prompts    01-intake.md    02-triage.md    03-clarify.md    04-compose.md    05-check.md  templates/         # output formats per step    triage.md    questions.md    delivery-prd.md  requirements/      req-0001-questionnaire/    meta.yaml        # type, route, version, status    00-inputs/       # raw materials, read-only    sources.md       # source registry    triage.md        # triage conclusion + validation    questions.md     # clarification questions    decision-log.md  # every decision: time, who, why    drafts/          # route B intermediate drafts    delivery/        PRD.md           # delivery requirement doc (unified exit)        interaction.html # when needed        v2/              # iteration output from prd-iterate

Three layers: AGENTS.md, playbook/, templates/ — the process itself; written once, tuned after a few runs. requirements/<id>/ — per-requirement materials and outputs; one per requirement. meta.yaml — where this requirement stands; updated at each step end.

What used to live in prompts now lives in playbook/ and templates/ — write once, reuse every requirement.

AGENTS.md: Rules and Entry

# product-os rules1. 00-inputs/ read-only; raw materials never rewritten.2. Every scope, rule, acceptance in delivery doc must trace to a source; untraceable = "to confirm", no invention.3. "approved" only human writes.4. ANY change (new material, verbal change, review comment) re-enters at 01 Intake; never edit delivery/PRD.md directly.## Flow entryOn "process req-xxxx" or "continue req-xxxx":1. Read requirements/req-xxxx/meta.yaml2. By status find next step, execute corresponding playbook/ file3. Update status each step; pause at human gates

Rule 4 is the key to "fixing" the flow. Allow bypassing and within two weeks you're back to chaos.

meta.yaml: Resumable Checkpoint

id: req-0001-questionnairetype: new          # new / change / iteration / optimizeroute: A          # A organize / B rebuild / C iterateversion: v1.0baseline: null    # iteration: path to previous delivery/PRD.mdstatus: intake-done # intake-done → triaged → clarifying → drafted → ready-for-review → approved

With status, a new session only says "continue req-0001". Agent reads meta.yaml and resumes — no re-explaining context.

How the Five Steps Run

Each step: one playbook command, one output, one completion criterion.

01 Intake: Register First, Understand Later

# playbook/01-intake.mdRead all files under requirements/<id>/00-inputs/.1. Do not modify any original file.2. Log each material in sources.md: ID | filename | type | provider | note (date, version)   Types ONLY: requirement-doc / dev-doc / interaction-html / design / verbatim / existing-page / chat-log / review-comment3. Word/PDF → text copy into 00-inputs/_text/; originals untouched.4. Designs: log link or screenshot path only; no guessed descriptions.5. Set meta.yaml status = intake-done.

Completion: every line in sources.md maps to a file in 00-inputs/, none missing.

Product's dev doc also goes into 00-inputs/ as reference — it does NOT become dev-slim directly because it hasn't passed scope/source checks.

02 Triage: Classify, Pick Route

# playbook/02-triage.mdRead sources.md and 00-inputs/, fill triage.md per templates/triage.md:1. Type: new / change / iteration / optimize — write one-sentence rationale.2. Baseline: any previously delivered delivery/PRD.md? write path.3. Material health-check: scope, not-do, page list, states/exceptions, biz rules, interfaces, acceptance — each marked "complete / missing / conflict" with source line ref.4. Separately list: crossed-out or "ignored" sections; conflicts between materials and existing pages.5. Propose route per rules below, with reason.PAUSE — wait for human route confirmation.

Route rules live in the template, not daily judgment:

Has delivered baseline AND new round of requirements → C iterateNo baseline AND scope OR acceptance any "missing" → B rebuildElse → A organize

Rules are the author's current split; adjustable after a few runs. Key: rules written down, every judgment traceable.

Completion: reading triage.md alone lets you decide the route without re-reading raw materials.

03 Clarify: Only Blocking Questions

# playbook/03-clarify.mdFrom triage.md items marked "missing" and "conflict", write questions.md per templates/questions.md.Each question: - ID (Q1, Q2...) - who to ask - why ask - consequence if unanswered - your suggested default answerOnly blocking questions: unanswered = cannot write delivery doc. Do NOT answer for stakeholders.

Answers go into decision-log.md; question marked closed. If no answer arrives, proceed with default but note "handled by default assumption" in delivery doc.

Completion: questions.md has no open blocking questions, or every one has a default assumption recorded.

04 Compose: Three Routes, One Exit

# playbook/04-compose.mdExecute per confirmed route in triage.md; final output always delivery/PRD.md (template: templates/delivery-prd.md).- Route A: directly organize from 00-inputs/ into template.- Route B: first draft with /pm-execution:write-prd into drafts/; if many page states or cross-page flows, generate delivery/interaction.html via html-design-prototypes; then organize draft into template.- Route C: invoke prd-iterate (baseline_prd = previous delivery/PRD.md, out_dir = v2/); then organize iterated PRD into template, embed change-map at top.Every scope, rule, acceptance cites source: sources.md ID or questions.md ID."Verbatim" materials: quote original only, no rewrite or polish.

Route B note: pm-skills ' create-prd outputs an 8-section PRD, structure differs from the delivery template — so it stays in drafts/ as a draft, never the delivery doc.

Unified delivery template:

# Delivery Requirement Doc · <name>> Version: v1.0 | Status: draft | Type: new | Route: A | Baseline: none## 1. Sources & Versions## 2. Background & Goals## 3. Scope### Do### Not Do### Not Covered## 4. User Flows & Page List## 5. States & Exceptions## 6. Business Rules## 7. Data & Interface Dependencies (known / to confirm)## 8. Interaction & Visual References (HTML, design links)## 9. Acceptance Criteria## 10. Change Log

Completion: every template section filled or marked "not applicable"; no scope item without a source trace.

05 Verify: Machine Checks Structure, Human Checks Judgment

# playbook/05-check.mdCheck delivery/PRD.md item by item, append results to triage.md "verification" section:- Template sections complete- "Not Do" not empty- Every scope, rule, acceptance has source ID- questions.md: no open blocking, or defaults recorded- Route C: run prd-iterate's validate-output.sh, must passAll pass → status = ready-for-review. "approved" only human sets.

Route C validation command:

SKILL=plugins/frontend-team-toolkit/skills/prd-iteratebash $SKILL/scripts/validate-output.sh requirements/req-0001-questionnaire/v2

Machine only checks structure: sections exist, sources cited. "Not Do" correctness, default assumption acceptability — human review.

Completion: you write approved into meta.yaml.

Real Requirement Walkthrough

Example: an online questionnaire page — user answers questions, system gives assessment; mismatched conclusion requires declaration confirmation. An existing similar page runs in production. The example uses real material shapes and final dev-slim; intermediate triage.md, questions.md are reconstructed.

Intake: 4 Materials + 1 Live Page

sources.md

(anonymized):

| ID | filename | type | provider | note ||---|---|---|---|---|| S1 | attachment1-questionnaire.docx | verbatim | biz | questions & prompt copy || S2 | attachment2-conclusion-declaration.docx | verbatim | biz | conclusion copy & declaration || S3 | system-PRD.html | requirement-doc | product | rules source, dozens of sections || S4 | mobile-wireframe-flow.html | interaction-html | product | page flow reference || S5 | live-old-page (code path) | existing-page | — | layout, interface, submit flow baseline |

Two lessons already baked into playbooks:

Word → text first. Agent may not read .docx. Convert at intake:

textutil -convert txt -output 00-inputs/_text/S1.txt 00-inputs/attachment1-questionnaire.docx

(macOS built-in). Originals untouched.

"Verbatim" as separate type. S1, S2 are formal biz copy — delivery and dev docs must quote, not let AI polish. Typing them out lets every later step know they're frozen.

Triage: Materials Clash

triage.md

health-check (reconstructed):

Type: iteration (S5 is live similar page, this round swaps rule set)Baseline: live old page S5| item | verdict | source ||---|---|---|| scope | conflict: S4 flow has extra independent steps vs S5 | S4, S5 || not-do | missing; also S3 has two crossed-out "ignored" sections | S3 || states/exceptions | complete but scattered across S3 sections | S3 || biz rules | complete: multiple judgment rules, stackable | S3 || interface | missing: external validation interface path not given | S3 || acceptance | missing | — |Proposed route: C iterate

Three findings directly impacting dev effort:

Interaction HTML vs live page conflict. Wireframe adds steps. Can't let AI guess — must ask.

PRD has crossed-out sections. Agent reading HTML may treat strikethrough as content. Health-check explicitly lists them in "Not Do" with source.

Interface not ready. Don't wait, don't invent. Proceed with default assumption, document pre/post handling.

Clarify: Put Conflicts Before Stakeholders

questions.md

(two items):

Q1 · ask product · page flow per wireframe or keep live old page?  consequence: page structure totally different, highest rework risk  default: keep live old pageQ2 · ask backend · when will external validation interface be ready?  consequence: one judgment category cannot connect  default: reserve call site; before connect treat as "no hit"

Final decision: follow live page; wireframe extra steps all moved to "Not Do".

Final Output Metrics

Resulting dev-slim numbers showing what the flow protected:

~250 lines, within skill's 80–250 line range.

6 "Not Do" items, each with reason; crossed-out sections and wireframe extra steps all captured.

Only 1 blocking item left — the external interface — carried with default assumption.

Page split into 4 modes; mode transitions, switch conditions, cleared states tabulated separately.

Review day confirmed 5 details; version v1.0 → v1.1 handled as "change", change log itemized.

Had these conflicts surfaced during coding, the rework would have been the entire page structure.

Changes, Iterations, Optimizations: Same Entry, Three Paths

Requirements always change. Flow stays fixed by routing all changes through the same entry; triage splits them:

Change: current version not yet delivered, scope/rules altered → new materials into 01 → triage = change → edit original delivery doc, version v1.0 → v1.1.

Iteration: previous version delivered, new round arrives → triage = iteration → route C, prd-iterate produces v2/, version → v2.0.

Optimization: scope unchanged, doc improvements (add states, acceptance, rephrase) → triage = optimize → only run steps 04, 05, version v1.0 → v1.0.1.

Versioning borrows semantic idea: major = iteration, minor = change, patch = optimization. Glance at version → know history.

All three share one rule: change log must state which clauses changed and their source IDs . Verbal changes also need a text record in 00-inputs/ (chat screenshot, meeting notes) before re-entering intake.

Questionnaire example continued:

Iteration: this requirement itself was an iteration. Live page exists; new rule set. Old page layout/submit flow frozen; questions and judgment rules mandatory changes.

Change: review day confirmed 5 details (e.g., incomplete-answer prompt, new field on submit). Delivery doc v1.0 → v1.1, each logged with new review-comment source.

Optimization: if acceptance too vague, scope unchanged → only beef up acceptance (e.g., "can submit after all answered" → "missing 1 question blocks conclusion page"), version v1.0 → v1.0.1.

Four Skills: Where They Fit

pm-skills

' create-prd → step 04, route B only; when materials too poor, need full redraft. html-design-prototypes → step 04, route B only; no usable interaction HTML, many states or cross-page flows. prd-iterate → step 04, route C only; delivered baseline exists, new iteration round. prd-three-layer-template → downstream after delivery; converts delivery doc to dev-slim.

Route A uses zero skills. Good materials → organize into template is enough.

Installation notes:

Only install pm-execution plugin from pm-skills; full install causes trigger conflicts.

claude plugin marketplace add phuryn/pm-skillsclaude plugin install pm-execution@pm-skills

html-design-prototypes

per f-labs-io/agent-html-skills repo; input must include design links and existing component names or it invents new visuals. prd-iterate and prd-three-layer-template live in frontend-team-toolkit plugin. Their SKILL.md set disable-model-invocation: true — model never auto-triggers; playbook decides when to call. Exactly what fixed flow demands.

After Delivery: Downstream Handoff

Once approved, delivery package goes to dev. Current separate handling:

delivery/PRD.md (approved)  → /prd-three-layer-template convert → dev-slim  → coding: run ai-frontend-dev-workflow or let AI follow dev-slim

Delivery template sections deliberately align with dev-slim skeleton to avoid loss on conversion:

Background & Goals → Background

Scope (Do/Not Do/Not Covered) → Scope (Feature List/Not Do/To Confirm) — Not Covered blocking items become To Confirm

States & Exceptions + Biz Rules → Implementation Spec (merged into executable specs)

Data & Interface Dependencies → Interfaces — unconfirmed interfaces must NOT have invented paths

Interaction & Visual References → Pages & Interactions (reference HTML/designs)

Acceptance Criteria → Acceptance Criteria

Change Log → Change Log (with version)

Conversion uses convert directly; don't expand to full then compress back:

/prd-three-layer-template convert requirements/req-0001-questionnaire/delivery/PRD.md to dev-slim for AI

Coding Agent reads ONLY dev-slim. 00-inputs/ product dev docs, route B drafts — never enter coding workflow.

Two reusable patterns from the questionnaire dev-slim:

Header workflow-hint:

> **workflow-hint**: `target-mode: brownfield` | `workflow-mode: mini` | `blocking-policy: assume-with-risk`

Three fields tell coding workflow: brownfield project, run mini profile, unresolved blocking items handled by default assumption. Requirement side and coding side connect in this one line.

Interaction details as pointers, not full copy. Wireframe state machine long; pasting into slim drowns specs. Instead, header pointer to separate interaction analysis file; slim keeps only mode definitions, switch conditions, cleared states.

After Prompts Become Files

Fixed flow reduces per-requirement work to: drop materials into 00-inputs/, say "process req-xxxx", decide at three human gates.

Old prompt pile → five playbooks + three templates. Difference: they're now improvable. A question type always missed → edit 03-clarify.md; delivery doc always missing a section → edit delivery-prd.md. Fix once, every future requirement benefits.

After several stable runs, next step: bundle playbook/ and templates/ into a custom Skill, also disable-model-invocation: true, invoked by name. Then product-os graduates from a directory convention to a distributable tool.

The author has packaged product-os as a skill (screenshots omitted).

Common Pitfalls

Flow collapses in two weeks → not bad design; someone bypassed intake and edited delivery doc directly.

Triage conclusion ignored → not ceremonial; triage didn't pause for human route confirmation.

Route B draft treated as delivery doc → not because draft looked complete; 8-section PRD skipped template & source checks.

Delivery doc has interface path, backend says none → not AI hallucination; untraceable content not marked "to confirm".

Version numbers chaotic → not trivial edits skipped; change/iteration/optimize not separated at triage.

Next Is FDE, But No Shortcuts

This is step one of frontend merging into product: fix requirement doc production.

Further out, senior frontend becomes FDE (Forward Deployed Engineer): on-site, turn a concrete problem into a daily-used customer process. But FDE isn't grown fast by tools . Needs project scars: seen enough sites, mis-scoped, been rewritten, inherited messes. No shortcut.

Author's earlier Datawhale case article: FDE step one — shadow a doer for a day. Can't learn from docs; only repeated site visits.

Roadmap stages:

Frontend: turn designs + APIs into stable pages — done.

Merge into product: turn pile of materials into clear-scope deliverable requirements — just started.

Own a product line: responsible for product outcome, not just a requirement — not yet.

FDE: scope within customer constraints, own business result — far away.

What does current stage do for later? Turn every requirement's experience into reviewable artifacts. product-os yields three natural experience logs: triage.md: what materials missed, where contradictions lay. questions.md: which questions repeatedly force stakeholder callbacks. decision-log.md: why each scope set that way, later changes.

Monthly review: most-missing material → tells you what to ask stakeholders upfront; most-reverted decision → tells you where your judgment drifts. After a year, these logs ARE your project experience. Then talk FDE with something in hand.

Summary

One thing: fix "requirement materials → delivery requirement doc" — stop rewriting prompts per requirement.

One entry: all materials and changes enter at 01 Intake; no bypass to edit delivery doc.

Five fixed steps: intake, triage, clarify, compose, verify — each with playbook, output, completion criterion.

Three routes, one exit: organize/rebuild/iterate by triage rules; all land on same delivery doc template.

Three change types: change/iteration/optimize split at triage; version numbers distinguish.

Exit aligned downstream: delivery doc sections map to dev-slim; conversion loses nothing; coding reads only dev-slim.

FDE slowly: solidify this stage, accumulate reviewable experience per requirement — more useful than rushing FDE talk.

If you do only one thing: take the prompt pile for your next requirement and split it into five playbook files. Write once, reuse forever; fix the one that hurts.