Capture everything. Question intelligently. Approve with confidence.
An AI-native platform that replaces requirement gathering with structured, continuously evolving discovery — making ambiguity, missing information, disagreement and assumptions visible, and the final business intent unambiguous. Companion artefacts: DISCOVERY_SPEC.md (canonical text) and prototype/discovery-engine.html (clickable).
How to read this document
Each module is one card: purpose → prototype screenshot → how the flow works → features built now vs later → acceptance criteria → benefits → build note. Modules are grouped under phase banners; stable slugs (m-…) match the clickable prototype's views, so every screenshot can be opened live.
Vision & architecture principles
One question governs everything: “Do we understand this product well enough that another team can build exactly what the business intends, without going back to the customer for missing requirements?” The engine behaves like a seasoned PM, BA, UX researcher, domain expert, requirements engineer and QA reviewer working together — for a single owner first (Chandra Jewellery ERP is project #1), with a fully domain-agnostic core.
Five knowledge layers — never mixed
| Layer | Holds | Mutability |
|---|---|---|
| 1 · Raw knowledge | Inbox captures, verbatim | Append-only, immutable |
| 2 · Discovery knowledge | AI/user proposals, questions, conflicts, register suggestions | Proposed → human-triaged |
| 3 · Canonical requirements | The single source of truth, versioned | Human acceptance only |
| 4 · Derived artefacts | Spec views, persona views, prototypes, packages | Regenerated, never hand-forked |
| 5 · Governance | Rules · guardrails · golden paths · standards · component registry | Living, user-editable, scoped |
Every view — full spec, feature spec, persona view, reviewer view, executive view, prototype, questionnaire, sign-off package — derives from layer 3 and shows a stale badge the moment canonical moves on. Views can never silently diverge. And no relationship is ever lost: source ↔ question ↔ answer ↔ requirement ↔ rule ↔ persona ↔ workflow ↔ prototype ↔ comment ↔ review ↔ acceptance ↔ approval are first-class links, rendered as a timeline on every requirement.
Every AI capability runs on Claude Code — claude -p
Owner decision: no LLM API, no API keys. The engine runs on a machine with Claude Code installed and authenticated; every AI feature — synthesis, questions, reviews, chat, prototypes, packages — executes as a headless CLI job.
- A user action (Synthesize, Generate questions, AI review…) creates a visible AI Job.
- The runtime assembles a context bundle — a temp folder of plain files: relevant captures, canonical requirements, glossary, and the governance in force at that scope.
- It invokes
claude -p "<instruction>" --output-format jsonwith a per-capability model (haiku / sonnet / opus) and restricted tools; long tasks stream, follow-ups reuse the session via--resume. - Structured output is validated, then written only as layer-2 proposals — an AI job can never touch the canonical store (blocking guardrail).
- The job record keeps model, duration, cost, the exact input manifest and a why for every proposal — visible in the AI Console.
A premium shell where nothing is ever lost
Before any AI runs, the engine must be a joy to capture into: the app shell, the project hierarchy, the append-only Discovery Inbox, the canonical requirement model and the shared business language.
Application shell & experience framework
P1 · PHASE 1The engine must feel like a modern, premium, AI-native product — never an enterprise CRUD app. A complex discovery process has to feel simple: keyboard-first, progressive disclosure, minimal cognitive load.
Built in this phase
Dark-teal sidebar (collapsible rail, mobile drawer), blurred topbar, project switcher, global search, light/dark themes on chandra-ui tokens.
Navigate anywhere, capture a thought, trigger synthesis, search any entity — the whole product is keyboard-drivable.
Designed empty states (with next best action), skeleton loaders, actionable errors, consistent status pills on every screen.
One consistent ring/bar language for confidence & completeness — every score expands to its breakdown, everywhere.
Full desktop experience; capture, answering, review and reading first-class on mobile.
Acceptance criteria — definition of done
- Every screen is reachable and operable by keyboard alone; the palette opens in under 100 ms.
- Theme toggles without re-render; no unstyled empty/loading/error state exists anywhere.
- All UI derives from the approved chandra-ui component set and house tokens — zero one-off components.
Workspace & project hierarchy
P1 · PHASE 1Organization → Workspace → Product → Project → Module → Feature → Requirement, with middle levels optional per project. Granular ownership: PM-A can own Feature A while PM-B owns Feature B.
Built in this phase
Hierarchy depth is project configuration, not code; every node has an owner and a breadcrumb path shown on all its objects.
Owner, PM, Contributor, Reviewer, Stakeholder (magic-link only), Observer. Permissions inherit down and can be overridden per node.
Description, attached domain pack, methodology config, AI toggles, governance in force, members, health summary.
Acceptance criteria — definition of done
- Any requirement can answer: who owns me, who may edit me, who must approve me — from hierarchy + approval matrix alone.
- Two PMs owning sibling features cannot edit each other's canonical content without permission.
Discovery Inbox
P1 · PHASE 1The always-open capture surface for layer 1. Thoughts, notes, meetings, transcripts, customer input, emails, WhatsApp, documents, existing requirements, reviewer feedback — captured in seconds, immutable forever, and never triggering a rewrite.
- Capture from anywhere — ⌘K, the Capture button, or drag-drop a file. Choose a source type, author and optional feature link.
- The capture is stored append-only with source, author, timestamp, context and tags. Corrections are new captures marked “supersedes”.
- Days of captures accumulate — the spec does not move. A badge counts unsynthesized items.
- When you choose, run Synthesize over the accumulated scope (module m-synthesis).
- Every capture forever shows its downstream trace: synthesis runs that read it, proposals and requirements that cite it.
Built in this phase
Thought, Note, Meeting, Transcript, Customer input, Email, WhatsApp, Document, Existing requirement, Reviewer feedback, Other.
Search, operator filters (type, author, feature, tag, date range, status), sort, pagination — the STD-LIST golden path applied to itself.
New → Filed → Included in synthesis → Superseded/Archived. Nothing is ever deleted.
Optional (default OFF): suggests tags and feature links only — never content changes.
Edge cases & handling
- Wrong capture? It's immutable — add a superseding capture; both stay traceable.
- A capture relevant to three features links to all three; synthesis for any of them may read it.
- Huge transcript files are stored whole; synthesis bundles excerpt them by relevance.
Acceptance criteria — definition of done
- Adding 50 captures changes nothing in any requirement or derived artefact.
- Every capture's downstream trace (synthesis runs, proposals, requirements) is navigable from the capture.
- A capture can be filed to a feature in at most two interactions; quick capture via ⌘K in one.
Artefact Bridge — import & external round-trip
P1 · PHASE 1The engine is not a walled garden. Bring an existing document/prototype in (adopt work you built elsewhere), or send one out to edit directly in Claude Code and reconcile when done. Both run through one mechanism — reverse-synthesis: an artefact is read into layer-2 proposals, never straight into canonical.
- Import: paste a link or upload a PRD/prototype from another Claude Code session; reverse-synthesis proposes requirements, fields, rules, criteria and journeys — each citing its location in the source — plus registers the prototype with screen ↔ requirement links and orphan-UI flags.
- Check-out: mark an artefact “out for external editing”; the engine records the baseline it handed off, and who/when.
- Edit outside: you fix comments and requested changes directly in Claude Code — no engine involvement.
- Bring back: point the engine at the edited artefact; it diffs the return against the baseline.
- “Mark as fixed”: Reconcile (default) folds the changes into canonical as proposals and resolves the addressed comments; Quick just marks comments Addressed. Either way the external edit is logged in requirement history.
Acceptance criteria — definition of done
- Importing a PRD+prototype yields a triage board of requirement proposals, each citing a source location, plus a registered prototype with screen↔requirement links and orphan flags.
- After an external edit, “mark as fixed” resolves the addressed comments and — in reconcile mode — leaves canonical equal to the returned artefact.
- The external-edit event (who, when, baseline → returned, tool = Claude Code) appears in requirement history; no comment is lost across the round-trip.
Canonical requirement model
P1 · PHASE 1Layer 3 — the single source of truth. One requirement is one screen-worth of structured, versioned, fully traceable knowledge, with per-section completeness and no vagueness allowed at field level.
What it covers
Built in this phase
Each applicable section individually tracked for completeness; the section set comes from methodology config, not code.
Every field: name, label, purpose, type, required, default, allowed values, min/max, format, validation, error message, visibility, editability, persona access, dependencies, conditional behaviour. “Validate the field” is flagged as vague — the exact rule must be written.
Any list a requirement defines gets search, operator filters (=, ≠, contains, starts/ends, >, <, ≥, ≤, between, date range, multi-select), sort, pagination — unless the requirement states an explicit exception.
Every view answers export YES/NO; if YES — formats, columns, ordering, applied filters, formatting, grouping, totals, permissions, file naming, PDF layout. Export never means “data dump”.
First-class notifications: trigger, recipient, channel, subject, exact message with placeholders, timing, example. Feature ↔ notification navigable both ways; project-wide catalog.
GIVEN/WHEN/THEN covering happy path, validation, permissions, exceptions, errors, transitions — precise enough for a future automated testing agent.
Draft → Proposed → In Review → Approved (+ Deprecated). Every change is a version with author, cause (edit / proposal / comment / answer) and diff — history is never overwritten, deletion is impossible.
Business value, urgency, customer impact, risk, dependency, strategic importance — scheme configurable, no hardcoded methodology.
Acceptance criteria — definition of done
- A fully-filled requirement shows 100% structural completeness with a visible per-section breakdown.
- Any historical version can be reconstructed and diffed against any other.
- Every requirement renders its full evolution timeline: raw note → question → answer → version → comment → revision → approval.
Glossary, calculations & policy library
P2 · PHASE 1Shared business language: terms, formulas and reusable policies referenced across features — and injected into every AI context bundle so generated text always speaks the business's language.
Built in this phase
Term, definition, synonyms, owner, status, usage links — e.g. “Quotation”, “Design change”, “Karigar”, “Approval”.
Business formulas in business notation with worked examples (Margin = Selling Price − Cost; CALC-2 quotation pricing), reusable and linked to every requirement that uses them.
Reusable rules (discount authority, approval evidence) referenced by many features — change once, see everything affected.
Flags spec text using undefined or conflicting terms (advisory).
Acceptance criteria — definition of done
- Renaming a term shows every usage; a policy lists every referencing feature.
- AI-generated text uses glossary terminology (verified by the consistency lint).
AI that proposes — never decides
The Claude Code runtime turns raw knowledge into structured proposals, intelligent questions and register entries. Governance shapes every job; the AI Console prices every job; humans triage everything.
Claude Code AI runtime & console
P1 · PHASE 2Every AI capability is a visible, queued, priced job executed via claude -p — no API, no keys. The console shows toggles, history, models, durations and the exact inputs of every job.
Built in this phase
Queued / running / succeeded / failed, concurrency 1 by default; failures explain themselves and offer retry — no partial silent writes.
Per capability: instruction template, output schema, default model (haiku = light, sonnet = core, opus = heavy), toggle. All configuration, not code.
Enforced in code and mirrored as GG-2: AI writes layer-2 proposals, never canonical objects, approvals or review verdicts.
Each job stores its exact input manifest — “what did the AI see?” is always answerable.
Every proposal carries source references + reasoning summary, shown on demand.
Acceptance criteria — definition of done
- With all toggles OFF, zero claude invocations occur anywhere in the product.
- Every historical job answers: model, inputs, outputs, why, duration, cost.
- A killed CLI process leaves no half-written proposals.
claude -p --output-format json (stream-json for long jobs, --resume for sessions, restricted --allowedTools); temp-dir context bundles assembled from the canonical store.Governance framework
P1 · PHASE 2Four living, user-managed concepts — Governance Rules, Guardrails, Golden Paths, Standards — scoped Global → Feature with explicit precedence. Never hardcoded; add a rule in plain language and it joins the very next AI context bundle.
How the flow works
- Type a rule as you'd say it: “From now on, every approval feature must define timeout and escalation.”
- Classify: type (rule / guardrail / golden path / standard), scope (global → feature), severity (advisory / needs-approval / blocking).
- It's data now — included in every relevant context bundle; no master-prompt rewriting, ever.
- Violations are flagged with an explanation; blocking guardrails stop the job (e.g. GG-1: never generate a component outside the approved library; GG-3: no technical architecture in outputs).
- The “effective governance” view resolves precedence for any node in the tree.
Built in this phase
Rules guide, guardrails bound, golden paths prefer (STD-LIST, approval pattern, designed empties), standards normalize (dates, currency).
chandra-ui's ~70 approved components as governance data; every generated UI element must map to one.
Section sets, question categories, readiness checklist, scoring weights — per project; no single hardcoded PM methodology.
When a component changes: list affected prototypes/screens/specs, offer “update affected artefacts?” with a diff first.
Acceptance criteria — definition of done
- Adding a rule changes the very next AI job's context bundle.
- The effective-governance view correctly resolves override/extend precedence for any node.
- A blocking guardrail demonstrably stops a violating generation, with an explanation.
Synthesis engine
P1 · PHASE 2The explicit “make sense of everything new” action. Reads unprocessed captures + accepted answers + accepted comments in scope; produces cited proposals, surfaced conflicts, duplicates and a human-readable change summary. Canonical is untouched until you accept.
- Choose scope (project / module / feature) and run — one claude -p job over a reproducible bundle.
- The engine de-duplicates, maps information to existing requirements, and detects contradictions, assumptions, missing information and affected workflows / personas / UI / rules / notifications / criteria.
- A change summary appears: “4 changed · 2 new · 2 conflicts · 3 questions resolved · 5 new questions · 2 screens affected.”
- The triage board groups results: Added · Changed · Removed · Conflicting · Unresolved · Newly inferred — each proposal with side-by-side diff, sources and why.
- You accept / edit-then-accept / reject / defer. Accepting creates a new requirement version citing the proposal. For major changes, an impact preview (other requirements, screens, reviews affected) appears first.
- Conflicts (“only managers approve” vs “sales can approve”) and possible duplicates are never auto-resolved — merge, keep both, or mark intentionally different.
Acceptance criteria — definition of done
- A run over 30 captures yields a triage board where every proposal cites at least one source.
- Rejecting all proposals leaves the canonical store byte-identical.
- The change summary always matches the triage board contents exactly.
- Conflicts and duplicates require human resolution; “intentionally different” suppresses future duplicate flags.
Question engine — generator + adaptive interviewer
P1 · PHASE 2“Generate 20 questions” yields the most important unanswered questions — categorized, prioritized, each with a stated reason. Answers that introduce ambiguity spawn follow-ups, like an adaptive interviewer (real-time follow-ups are a cost toggle, default OFF).
Built in this phase
Per feature, any count; no filler — duplicates of answered questions are filtered; each question says why it matters.
Business, User, Workflow, Rule, Validation, Permission, UX, Exception, Notification, Reporting, Integration, Compliance, Operational.
“Only if the customer changes the design” → what is a design change? does it return to draft? is approval invalidated? who reapproves? is the customer notified? is pricing recalculated? Toggle ON = in-portal; OFF = proposed at next synthesis.
Priority, owner, stakeholder, due date, status, answer, affected requirements — visible until resolved; full question → requirement traceability.
Acceptance criteria — definition of done
- Generated questions never duplicate an already-answered question.
- Every question shows answered-by-whom, when, and the requirement version(s) it produced.
- Follow-ups appear in real time only when the toggle is ON; otherwise at next synthesis.
Discovery registers
P2 · PHASE 2Assumptions, Risks, Decisions (with alternatives & trade-offs), Constraints and Dependencies — consistent, linked, never hidden in prose. Constraints feed every relevant AI bundle so they shape future discovery.
Built in this phase
Source, author, confidence, status: Open / Confirmed / Rejected / Converted to Requirement — with the original record and source chain preserved.
Probability × impact, owner, mitigation, affected requirements, status.
Decision, alternatives considered (Options A/B/C with benefits, disadvantages, cost, complexity, user & business impact), rationale, decision maker, date, affected requirements. AI may compare — never auto-chooses. The reason behind a decision is never lost.
Regulatory (GST series, BIS hallmarking), operational, financial, organizational, UX, timing, customer-specific.
Typed links — depends-on, conflicts-with, affected-by — visualized between requirements/features.
Acceptance criteria — definition of done
- Converting an assumption preserves the assumption record and its full source chain.
- The dependency graph renders both directions of every link; conflicts appear on both requirements.
- Every register entry (human- or AI-originated) carries sources.
Stakeholders answer, comment and formally approve
Magic-link questionnaires for stakeholders, inline comments that survive regeneration, formal reviews with visible disagreement, and scores that always explain themselves.
Questionnaire workspace & stakeholder portal
P1 · PHASE 3The PM composes questionnaires from open questions and sends tokenised magic links — no stakeholder accounts. Stakeholders state their name and answer by typing or device voice-to-text (transcript stored, no audio kept). The PM triages every answer and pushes accepted ones toward requirements.
- PM picks open questions relevant to a stakeholder, previews, and sends a magic link (scoped to that questionnaire; expiring; revocable).
- The stakeholder opens it on any device, states their name, and answers — typing, mobile text or voice typing. Progress saves; the same link resumes.
- If real-time follow-ups are ON, a clarifying question may appear right after an answer (adaptive interviewer); otherwise follow-ups queue for the PM.
- Each answer records question, respondent, timestamp, text, status — PM reviews, edits/interprets, accepts, rejects, partially accepts.
- Accepted answers feed the next synthesis (or “push to requirement” directly as a proposal) — full answer → requirement traceability.
- Outstanding responses are tracked with reminders; unanswered links show their age.
Acceptance criteria — definition of done
- A stakeholder with only a link answers everything on a phone without any login or app install.
- Every accepted answer is traceable from the requirement version it produced back to the respondent and timestamp.
- Revoked/expired links stop working immediately; partial progress is never lost.
Inline comments & push-to-requirement
P1 · PHASE 3Select any content in a spec view or prototype (desktop or mobile) and comment. Comments anchor to stable canonical IDs, survive regeneration, and can be pushed into the requirement they discuss — with the change traceable back to the comment.
How anchors survive regeneration — the design decision
data-req="R-102", section key, screen/element id). A comment stores (artefact-version, anchor-id, text-quote). On regeneration, anchors re-attach by ID first, then by fuzzy text-quote match; anything unmatched is flagged orphaned — never lost — and re-anchored manually in two clicks.Built in this phase
Author, timestamp, exact location/context, body, status (Open / Accepted / Rejected / Addressed), related requirement; threads with replies.
PM reads → edits/interprets → accepts → pushes: a proposal is created; acceptance produces a requirement version citing the comment.
Pinned to screen + UI element, staying linked to screen, element and requirement.
Unresolved comment counts roll up to feature and dashboard; “Has John's comment been addressed?” is answerable by spec chat.
Acceptance criteria — definition of done
- Regenerating a spec view after 20 edits re-attaches every ID-anchored comment; orphans keep their original quote and re-anchor in ≤ 2 interactions.
- Every accepted comment is traceable to the exact requirement change it caused.
Review workflow & approval matrix
P1 · PHASE 3Explicit reviewer assignment; formal verdicts with completion and confidence scores; an approval matrix (required / optional / final); and a consensus view that shows disagreement instead of hiding it behind an average.
Built in this phase
Only assigned reviewers give formal review (Approved / Approved with Comments / Changes Requested / Rejected / Not Reviewed); others read-only.
Per scope: Business Owner required, Sales Head required, Operations optional, CEO final — sign-off blocked until required + final approvals exist.
Each reviewer's outcome, completion and confidence side by side; divergence highlighted with its stated reason.
Reviews pin to a canonical version; if the requirement changes after review, the review is marked stale and the reviewer nudged.
Pending-review lists, due dates, reminder nudges.
Acceptance criteria — definition of done
- A feature with any required reviewer at “Changes Requested” can never appear approved anywhere.
- The consensus view lists every reviewer's individual scores — no averaged-only display exists.
- A requirement change after review reliably marks that review stale.
Completeness, confidence, quality & readiness
P2 · PHASE 3Four distinct, always-explainable measures. Completeness ≠ confidence (100% complete can be 60% confident). Document completeness ≠ knowledge completeness (a beautiful document with open critical questions scores low). No mysterious percentages — ever.
Built in this phase
Per-section percentages (Objective 100 · Workflow 90 · Rules 70 · Validation 80 · Permissions 60 · Notifications 40 · Acceptance 30 → 72%) with the breakdown always one click away; weights from methodology config.
Author + each reviewer's confidence retained individually; low-confidence reasons typed: business uncertainty, UX uncertainty, ambiguity, stakeholder disagreement, missing information, other.
Clarity, completeness, consistency, testability, traceability, ambiguity, stakeholder confidence — each dimension shows its why (e.g. flagged vague phrases).
Open questions, unconfirmed assumptions and unresolved conflicts count against knowledge completeness — shown beside document completeness.
Rollup (discovery, questions, rules, UX, acceptance, reviews) → READY / NOT READY with exact blocking reasons.
Acceptance criteria — definition of done
- Clicking any score anywhere opens its contributing breakdown.
- Two requirements with identical text but different open-question counts show different knowledge completeness.
- Individual reviewer scores remain visible wherever an overall score is computed.
AI reviewer, gap analysis & coverage
P2 · PHASE 3Before humans review, AI critiques: what's missing, ambiguous, contradictory; hidden assumptions; missing edge cases; unclear validation or permissions. Plus explicit gap analysis (“what have we not defined?”), workflow-vs-rules validation, and a coverage view that exposes orphaned information. All advisory — human approval remains authoritative.
Built in this phase
Per requirement/feature, on demand — one claude -p job; every finding carries why + sources; dismissals record who/when/why.
“You defined quotation approval but no rejection workflow.” Recommendations, never auto-requirements.
Run against methodology checklist + domain template + governance rules (e.g. GR-7 expects timeout/escalation on every approval feature).
Documented workflows checked against documented business rules before sign-off; contradictions flagged.
Requirements ↔ questions ↔ answers ↔ workflows ↔ criteria ↔ prototypes ↔ reviews; unlinked captures, answers and screens are listed.
Acceptance criteria — definition of done
- AI review of a feature missing exception handling flags it, pointing to the governance/template item that expects it.
- Coverage view lists every orphaned capture, answer and screen in scope.
- No AI finding can change canonical content without human acceptance.
Spec chat
P2 · PHASE 3Ask the specification itself: “Is customer approval covered?” · “Where is the approval timeout defined?” · “Has Meera's comment been addressed?” · “What's still incomplete?” Answers come only from canonical + sources, always with clickable citations. Toggleable; runs as resumable claude -p sessions.
Built in this phase
Project / module / feature scope; available as a slide-over on any requirement and as a full screen.
Every factual answer cites entity IDs that navigate on click; “not defined” is a first-class answer with an offer to create an open question.
Follow-ups reuse the CLI session (--resume) so context isn't resent; each conversation is a logged AI job.
Acceptance criteria — definition of done
- Every factual answer carries ≥ 1 citation that navigates to the cited object.
- Asking about something undefined yields “not defined” + a create-question offer — not a hallucination.
- With the toggle OFF, the chat surface is hidden and no jobs run.
See it, walk it, sign it off
AI-generated clickable prototypes on the approved component library, business journeys and process maps, the health dashboard, and a readiness-gated sign-off package containing only approved material.
Prototype Studio — AI-generated live prototypes
P1 · PHASE 4From selected requirements, claude -p generates clickable prototypes as live code — constrained to the registered chandra-ui component set (blocking guardrail). Desktop and mobile as distinct experiences; every element justified by a requirement; persona mode and scenario walkthroughs built in.
- Choose scope (feature/module) and target (desktop / mobile) — generation is manual-only, one opus-weight job pinned to a canonical snapshot.
- The context bundle carries requirements, personas, permissions, states, journeys, the component registry and UX golden paths.
- Generated screens reflect workflow, validation, states and navigation; every element carries
data-req— an element with no justifying requirement is flagged orphan UI. - Reviewers experience it as CEO / Sales / Operations / Approver… — only that persona's capabilities appear; scenarios (“customer rejects design after commercial approval”) highlight the relevant path step by step.
- When canonical moves, the prototype shows a stale badge; regeneration previews a screen-level diff and preserves comment anchors by requirement ID.
- AI UX review (advisory): usability, consistency, discoverability, complexity, accessibility, missing states/actions. Significant UX choices get Options A/B/C, recorded as decisions.
Acceptance criteria — definition of done
- Generated prototypes use only registered components — violations are blocked and listed (GG-1 has zero silent passes).
- Switching persona hides exactly the capabilities the permission sections deny.
- Every screen lists its justifying requirement IDs; every requirement lists its screens; orphan UI is impossible to miss.
- Regeneration never loses a comment — anchors re-attach or flag as orphaned.
User journeys, process maps & scenario walkthroughs
P2 · PHASE 4Business-readable journeys (Customer Inquiry → Design → Review → Customer Approval → Commercial Approval → Order) and process maps of actors, actions, decisions, approvals, exceptions and outcomes — never technical architecture. Every step links to requirements and prototype screens.
Built in this phase
Derived from approved requirements; regenerate on demand; stale badge; human label edits preserved where steps still match.
Actor lanes, decision diamonds, exception branches — readable by a non-technical reviewer.
Walk a named business scenario through journey + prototype, step by step.
Acceptance criteria — definition of done
- Every journey step resolves to at least one requirement; clicking navigates to requirement or screen.
- Scenario walkthroughs demonstrate the documented flow including its exception branches.
Discovery health dashboard
P1 · PHASE 4Completeness, confidence, unresolved questions, risks, assumptions, conflicts, pending reviews and approvals, prototype readiness, governance violations and AI recommendations — in one view where every number is clickable and explains itself. No single opaque score.
Built in this phase
Every tile expands to its reasons and navigates to the underlying items.
Per-feature readiness with blocking reasons, straight from the scores module.
Across snapshots: are open items falling and confidence rising?
Acceptance criteria — definition of done
- Every number on the dashboard lands on the exact underlying items when clicked.
- The “why not 100%?” panel is always present and current.
Readiness gate, sign-off package & handover
P1 · PHASE 4A final checklist gates “discovery complete”; only when it passes does the engine recommend READY FOR NEXT STAGE. The sign-off package contains only approved material, rendered business-readable in the house PRD style, from an immutable snapshot. Handover stays business-focused for the future Build Engine.
Built in this phase
Objective · stakeholders · personas · workflow · exceptions · rules · validations · permissions · notifications · list behaviour · exports · acceptance criteria · reviews · conflicts · critical questions · prototype review · governance — checklist content from methodology config.
The 24-part business package (executive summary → prototype → sign-off sheet); generation blocked while any required approval is missing.
Immutable snapshots at will and at every package generation; compare any two; history never overwritten.
Problem → User → Journey → Prototype → Rules → Outcome, presentation-friendly, zero internal complexity.
Acceptance criteria — definition of done
- Generating a package while a required approval is missing is impossible.
- Package content provably equals the approved canonical state at its snapshot.
- Unresolved items appear in the package under their own honest section — never hidden.
Every project makes the next one faster
Approved knowledge becomes searchable, reusable patterns; domain packs sharpen questioning; cross-project learning distinguishes known patterns from new requirements — never blindly copying.
Knowledge repository & reuse
P3 · PHASE 5All approved discovery knowledge becomes reusable product knowledge: pattern library, domain templates, cross-project search and multi-project learning.
Planned
Approved patterns (Standard Customer Approval Flow) reusable across projects, inserted as drafts with origin traceability preserved.
Jewellery, Manufacturing, Sales, CRM, Inventory, Approvals — terminology, workflows, rules, question sets, golden paths attached per project; never contaminating unattached projects.
Authorized users search approved knowledge across projects.
Reused knowledge is labelled known-pattern vs project-specific — never blindly copied.
Acceptance criteria — definition of done
- Reusing a library requirement records source library and original project.
- Domain template content never appears in a project that didn't attach it.
The module template
Every module in this document (and every feature the Discovery Engine itself will specify) follows the same checklist. Small modules may omit blocks; the acceptance-criteria block is mandatory.
- Overview — what & why
- Actors & roles
- Trigger & preconditions
- Primary flow (prose + diagram)
- Smart defaults
- Alternate flows
- Edge cases
- Use cases
- Validation rules
- Data model (prose only — business boundary)
- Roles (RBAC + ABAC)
- Audit hooks
- Report / export impact
- Acceptance criteria — definition of done
- Dependencies
Build order — first vertical slice
Walking skeleton before everything: Shell + Project + Inbox capture → manual Synthesize (one capability) → proposal triage → canonical requirement with versions & traceability → simple spec view. That slice exercises layers 1–4 end-to-end with one AI capability; modules then land in phase order, each as a vertical slice: understand → define UX → implement → test → validate acceptance → update docs → next.
claude -p, no API · comment anchors survive regeneration by canonical-ID anchoring.