# Discovery Engine — Product Specification

| | |
|---|---|
| **Product** | Discovery Engine — AI-native Product Discovery & Requirements Engineering platform |
| **Status** | Draft v0.2 — for review before implementation |
| **Date** | 2026-08-29 |
| **Owner** | Chandra (myailab2026@gmail.com) |
| **Companions** | `DISCOVERY_PRD.html` (illustrated document) · `prototype/discovery-engine.html` (clickable prototype) |
| **Style/UI basis** | `chandra-prd/docs/prd-kit/` house style · `chandra-ui` component library |

---

## 1. Vision

An AI-native platform that eliminates incomplete, ambiguous, poorly documented
requirements. It replaces traditional requirement gathering with a structured,
intelligent, continuously evolving discovery process, and behaves like an
experienced PM + BA + UX researcher + domain expert + requirements engineer +
QA-minded reviewer working together.

It is **not** a PRD generator, requirements editor, questionnaire tool, project
management tool, wireframing tool, or AI chatbot. It is a unified Product
Discovery Engine whose one fundamental question is:

> *"Do we understand this product/feature well enough that another team can build
> exactly what the business intends, without repeatedly going back to the customer
> to discover missing requirements?"*

It makes **ambiguity, missing information, disagreement and assumptions visible**;
makes **decisions traceable**, **requirements testable**, **prototypes
understandable**, and the **final business intent unambiguous**.

**First deployment:** single-tenant, for the owner's own use; first project is the
Chandra Jewellery ERP, but nothing in the core is jewellery-specific — domain
knowledge attaches per project (§6.21).

## 2. Core philosophy — the operating loop

```
CAPTURE → UNDERSTAND → QUESTION → CLARIFY → SYNTHESIZE → REVIEW → APPROVE
```

- Users dump raw information continuously (thoughts, meeting notes, transcripts,
  customer responses, WhatsApp text, emails, documents, observations, ideas,
  requirements, reviewer comments) **without** the system rewriting anything.
- **Synthesis is an explicit human act.** Nothing entering the inbox ever
  auto-rewrites the specification. Days of capture may pass; only when the user
  presses SYNTHESIZE does AI analyse accumulated material and propose changes.
- AI **suggests, analyses, identifies, summarizes, questions, recommends** — humans
  decide. The system never silently turns an AI inference into an approved
  requirement, and never silently destroys previous information.

Knowledge can also arrive as a **whole finished artefact** — an existing PRD or
prototype you built elsewhere (e.g. in a separate Claude Code session) — not only
as raw notes; and an artefact can leave the engine to be edited directly outside
it and be brought back. Both cross the same **Artefact Bridge** (§6.3B): the
artefact is read into *proposals* and reconciled into canonical by human triage,
so the canonical store stays the single source of truth and views never silently
diverge.

## 3. Architecture principles

### 3.1 Five separated knowledge layers

| # | Layer | Nature | Mutability |
|---|---|---|---|
| 1 | **Raw Knowledge** | Inbox captures, verbatim | Append-only, immutable |
| 2 | **Discovery Knowledge** | AI/user-structured: questions, answers, assumptions, conflicts, duplicates, proposals | Proposed → human-triaged |
| 3 | **Canonical Requirements** | The single source of truth | Changed only by human acceptance; fully versioned |
| 4 | **Derived Artefacts** | Spec views, persona views, prototypes, questionnaires, packages | Regenerated from canonical; never independently edited |
| 5 | **Governance** | Rules, guardrails, golden paths, standards, component library | Living, user-editable, hierarchical |

The layers never mix. Raw stays raw. Synthesis creates structured knowledge.
Approved structured knowledge becomes canonical. Everything shown to stakeholders
is derived. Governance controls how the whole process behaves.

### 3.2 Canonical source of truth

One canonical knowledge store per project. Full spec, feature spec, persona view,
reviewer view, executive view, prototype, acceptance criteria, questionnaires,
review packages and sign-off packages are all **views/derivations** of the same
underlying knowledge. They must never silently diverge; every derived artefact
records the canonical version it was generated from and shows a "stale" indicator
when the canonical store has moved on.

### 3.3 Business-first boundary

The engine's responsibility ends at business requirements, workflows, rules,
validations, roles, permissions, UX requirements, journeys, UI specifications,
prototypes, business acceptance criteria and business sign-off. It **never**
produces database schemas, API implementations, backend/infrastructure/deployment/
code architecture. Those belong to a future Design/Engineering Engine that
consumes the handover package (§6.20).

### 3.4 No loss of context

The relationships Source ↔ Question ↔ Answer ↔ Requirement ↔ Rule ↔ Persona ↔
Workflow ↔ Prototype ↔ Comment ↔ Review ↔ Acceptance Criterion ↔ Approval are
fundamental and are stored as first-class links (§7), never as prose conventions.

## 4. AI runtime — Claude Code only (`claude -p`)

**Decision (owner, 2026-08-29): the Discovery Engine uses no LLM API. Every AI
capability is executed by invoking the locally installed Claude Code CLI in
headless mode: `claude -p`.** The engine runs on a machine where Claude Code is
installed and authenticated with the owner's subscription.

### 4.1 How an AI job runs

1. A user action (Synthesize, Generate Questions, AI Review, Spec Chat, Generate
   Prototype…) creates an **AI Job** with a capability type.
2. The runtime assembles a **context bundle** — a temporary working folder of
   plain files: relevant captures, canonical requirements, glossary, applicable
   governance rules/guardrails/golden paths/standards, and the capability's
   instruction template.
3. It invokes `claude -p "<instruction>" --output-format json` (with
   `--model <per-capability model>`, restricted `--allowedTools`, and the bundle
   folder as working directory). Long jobs may use `--output-format stream-json`
   for progress. Follow-up turns in one logical task reuse the session via
   `--resume <session-id>` to avoid resending context.
4. Output is required to be structured (JSON per capability schema). The runtime
   validates it; malformed output is retried once, then the job fails visibly.
5. Results are written **only** into layer-2 Discovery Knowledge as *proposals*
   (guardrail — an AI job can never write into the canonical store).
6. The job record stores: capability, trigger, inputs manifest, model, duration,
   token/cost figures reported by the CLI, session id, outcome, and the produced
   proposals — powering the AI Console (§6.6).

### 4.2 Provider abstraction

An adapter interface (`run(job) → structured result`) isolates the engine from the
executor. v1 ships exactly one adapter: **Claude Code CLI**. The design permits
future adapters (other CLIs/models) without touching capability logic; capability
→ adapter/model mapping is configuration, not code.

### 4.3 Cost governance

AI is never assumed continuously active. Per-project toggles (with sensible
defaults): AI Chat ON/OFF · real-time follow-up questions ON/OFF · automatic
requirement suggestions ON/OFF · synthesis manual-only · AI review ON/OFF ·
prototype generation manual-only. The AI Console makes consumption visible:
jobs run, duration, models used, per-capability counts, and toggles in one place.

### 4.4 Explainability

Whenever AI proposes a requirement, question, rule, change or recommendation, it
must include a **why** (source references + reasoning summary) that the UI shows
on demand. No mysterious scores or silent inferences (§6.14).

## 5. Domain model (business-level, prose)

Core entities and their identity prefixes:

- **Workspace hierarchy:** Organization → Workspace → Product → Project → Module
  → Feature → Requirement (`R-###`). Hierarchy is configurable in depth; ownership
  and permissions attach at any node.
- **Capture** (`RAW-###`): immutable inbox item — source type, author, timestamp,
  context, tags, optional project/module/feature links.
- **Question** (`Q-###`): categorized, prioritized, owner, stakeholder, status,
  linked feature/requirements. **Answer** (`ANS-###`): respondent, timestamp,
  text (typed or device voice-to-text transcript; no audio retained), status.
- **Proposal** (`PROP-###`): an AI- or comment-originated suggested change to the
  canonical store (add/update/merge/split), with rationale and source links,
  awaiting human triage.
- **Requirement** (`R-###`): the canonical unit (structure in §6.4), versioned,
  with confidence, completeness, quality, priority, state.
- **Registers:** Assumption `ASM-###`, Risk `RSK-###`, Decision `DEC-###`,
  Constraint `CON-###`, Dependency links, Open Questions (view over `Q-*`).
- **Glossary term** (`G-###`), **Calculation** (`CALC-###`), **Policy/Rule**
  (`POL-###`) — reusable across features.
- **Notification spec** (`N-###`): first-class requirement objects in a catalog.
- **Comment** (`C-###`): anchored inline comment on any derived artefact.
- **Review** (`REV-###`): a reviewer's formal verdict + scores on a scope.
- **Prototype** (`PT-###`): a generated artefact with screens (`PT-###/s-name`),
  each screen mapped to requirements.
- **Governance items:** Rule `GR-###`, Guardrail `GG-###`, Golden Path `GP-###`,
  Standard `GS-###`, each with a scope level.
- **AI Job** (`JOB-###`), **Snapshot** (`SNAP-###`), **Sign-off package**
  (`PKG-###`).

All cross-entity relationships live in a single **trace-link graph** (§7).

## 6. Module specifications

Modules are grouped in five phases (vertical build slices). Stable slugs
(`m-…`) are shared by the PRD document sections and the prototype's views.
Functional requirements carry per-module IDs (e.g. `INB-01`) so this spec can
itself be imported into the Discovery Engine later (dogfooding).

---

### Phase 1 — Foundation & Capture

> Outcome: a premium, fast shell where all raw knowledge is captured and the
> canonical requirement model exists — before any AI runs.

#### 6.1 `m-shell` — Application shell & experience framework

The engine must feel like a modern, premium, AI-native product — never a
traditional enterprise CRUD app.

- **SHL-01** App shell per house style: dark-teal gradient sidebar (collapsible
  icon rail; off-canvas drawer on mobile), blurred sticky topbar with global
  search, project switcher, theme toggle (light/dark via `data-theme`), user menu.
- **SHL-02** Global **command palette** (⌘K): navigate anywhere, capture a
  thought, trigger synthesis, search entities — keyboard-first throughout.
- **SHL-03** Quality states everywhere: designed empty states (with the next best
  action), skeleton loading states, actionable error states, clear status pills.
- **SHL-04** Progressive disclosure: lists → detail slide-overs → full pages;
  contextual actions on hover/selection; minimal cognitive load.
- **SHL-05** Visual confidence/completeness indicators (rings/bars) reused
  consistently wherever a score appears; every score expandable to its breakdown.
- **SHL-06** Responsive web: full experience on desktop; capture, answering,
  review and reading flows first-class on mobile.
- **SHL-07** All UI built from the approved `chandra-ui` component set (tokens:
  teal #0FB5AE / indigo #5B5BF0, Space Grotesk / Inter / IBM Plex Mono).

*Acceptance:* every screen reachable by keyboard alone; palette opens < 100 ms;
theme flips without re-render; no unstyled empty/loading/error state anywhere.

#### 6.2 `m-workspace` — Workspace & project hierarchy

- **WSP-01** Hierarchy Organization → Workspace → Product → Project → Module →
  Feature → Requirement; middle levels optional per project (config, not code).
- **WSP-02** Granular ownership: any node has an owner; e.g. PM-A owns Feature A
  while PM-B owns Feature B. Owners default as approvers for their scope.
- **WSP-03** Roles: Owner, Product Manager, Contributor, Reviewer, Stakeholder
  (magic-link only), Observer (read-only). Permissions inherit down the tree and
  can be overridden per node.
- **WSP-04** Every governed object shows its scope path (breadcrumb) and owner.
- **WSP-05** Project home: description, domain knowledge attached, methodology
  config, AI toggles, governance in force, members, health summary.

*Acceptance:* a requirement can always answer "who owns me, who may edit me, who
must approve me" from hierarchy + approval matrix (§6.13).

#### 6.3 `m-inbox` — Discovery Inbox

The dedicated, always-open capture surface. **Capturing never triggers synthesis.**

- **INB-01** Capture types: Thought, Note, Meeting, Transcript, Customer input,
  Email, WhatsApp, Document (file upload), Existing requirement, Reviewer
  feedback, Other.
- **INB-02** Each capture records source, author, timestamp, context, optional
  tags, and optional links to project/module/feature. Multi-paragraph paste,
  drag-drop files, and quick-capture from the command palette.
- **INB-03** Captures are **immutable**; corrections are new captures linked to
  the original ("supersedes").
- **INB-04** Triage states: New → Filed (linked to feature) → Included in
  synthesis → Superseded/Archived. Nothing is ever deleted.
- **INB-05** Inbox list: standard list experience (§6.4 STD) — search, filters
  (type, author, feature, tag, date range, synthesis status), sort, pagination.
- **INB-06** A capture shows every downstream trace: which synthesis runs read
  it, which proposals/requirements cite it.
- **INB-07** Optional (toggle, default OFF): on-capture AI assist that only
  suggests tags/feature links — never content changes.

*Acceptance:* adding 50 captures changes nothing in any requirement; each
capture's full downstream trace is navigable; a capture can be filed to a feature
in ≤ 2 interactions.

#### 6.3B `m-bridge` — Artefact Bridge (import & external round-trip)

The engine is not a walled garden. Business documents and prototypes flow **in**
(adopt an artefact you already made) and **out and back** (edit it externally,
then reconcile). Both run through one mechanism — **reverse-synthesis**: an
artefact is read and turned into layer-2 *proposals*, never straight into canonical.

**Import / adopt an existing artefact**

- **BRG-01** Bootstrap a project from an existing PRD document and/or clickable
  prototype produced elsewhere (e.g. a separate Claude Code session) by **link
  (URL) or file upload** — no need to re-capture from zero.
- **BRG-02** Reverse-synthesis (`claude -p`) reads the artefact and proposes
  canonical requirements, sections, fields, business rules, notifications,
  acceptance criteria, journeys and glossary terms — each a triage proposal citing
  the exact location in the source. Human accepts/edits/rejects as in synthesis (§6.8).
- **BRG-03** The prototype is registered as a `PT-###` artefact; its screens are
  mapped to proposed requirements (screen ↔ requirement links). Screens with no
  matching requirement are flagged **orphan UI**; requirements with no screen as
  **uncovered**. Components are checked against the approved registry (§6.7);
  off-library components flagged.
- **BRG-04** Our own generated artefacts carry stable anchors (`data-req`, section
  keys, screen slugs) so re-import is exact; foreign artefacts get best-effort
  structural parsing, everything landing as reviewable proposals.
- **BRG-05** The imported artefact is preserved verbatim as a source (append-only,
  like a capture) so every adopted requirement traces back to it.

**External round-trip — "I fixed it outside, mark it fixed"**

- **BRG-06 Check-out.** Any derived (or imported) artefact can be marked **out for
  external editing**; the engine records the baseline version handed off and
  who/when. No lock (single-tenant, async).
- **BRG-07 Bring-back.** Point the engine at the edited artefact (updated link,
  re-uploaded file, or re-fetch of the same hosted file); it **diffs** the returned
  artefact against the baseline it sent out.
- **BRG-08 Reconcile to canonical (default mode).** The diff is reverse-synthesized
  into proposals so canonical catches up with what changed externally — preserving
  the "views never silently diverge" guarantee (§3.2). You triage (usually
  fast-accept, since you made the edits deliberately).
- **BRG-09 Comment/review resolution.** The engine maps external edits to open
  comments and requested changes and proposes marking them **Addressed**; you
  confirm in bulk ("all fixed") or cherry-pick. Comment anchors re-attach per
  CMT-02; unmatched ones flagged, never lost.
- **BRG-10 Quick mode.** Alternatively, "mark as fixed" simply flips open comments →
  Addressed, reviews → resolved and the artefact → in-sync **without** deep
  re-ingest — for cosmetic edits. Mode is chosen at bring-back; reconcile is default.
- **BRG-11 Audit.** The external-edit event (who, when, baseline → returned version,
  tool = Claude Code) is recorded in requirement history and the trace graph, so
  the round-trip never breaks the chain.

*Acceptance:* 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 (reconcile mode) leaves canonical equal to the
returned artefact, with the external edit recorded in history.

#### 6.4 `m-requirements` — Canonical requirement model

The heart of layer 3. One requirement = one screen-worth of structured truth.

**REQ-01 — Structured sections** (each applicable section individually tracked
for completeness): Why (problem) · Who (affected) · Personas · Business objective
· Workflow · Business rules · Validations · Field specification · Permissions ·
States · Transitions · Exceptions · Error handling · Notifications · Reporting ·
Search / Filtering / Sorting / Pagination · Export · Attachments · Acceptance
criteria · Sources · Confidence · Completeness.

**REQ-02 — Field-level specification.** Every form field documents: name, label,
purpose, data type, required/optional, default, allowed values, min/max, format,
validation rule, error message, visibility, editability, persona access,
dependencies, conditional behaviour. Vague entries ("validate the field") are
flagged by lint (§6.15) — the exact validation must be specified.

**REQ-03 — Standard list experience (STD-LIST golden path).** Unless a
requirement explicitly opts out (with a stated reason), every list page it
defines gets: search (+ autocomplete where sensible), filters with operators
(equals, not equals, contains, starts/ends with, >, <, ≥, ≤, between, date
range, multi-select), sorting, pagination, sensible defaults.

**REQ-04 — Export specification.** Every list/report/detail view answers "does
it export?" YES/NO. If YES: formats (Excel/CSV/PDF/other), columns, ordering,
filters/sorting applied, formatting, grouping, totals, permissions, file naming,
PDF layout. Export is never assumed to mean a raw data dump.

**REQ-05 — Notification catalog.** Notifications are first-class: trigger,
recipient, channel (in-app/email/WhatsApp/Slack/other), subject, exact message
with placeholders, timing, example. Feature → its notifications; notification →
its originating requirement. Project-level catalog view.

**REQ-06 — Acceptance criteria.** GIVEN/WHEN/THEN preferred; must cover happy
path, validation, permissions, exceptions, errors, state transitions; precise
enough for a future automated testing agent. Every criterion belongs to exactly
one requirement.

**REQ-07 — Lifecycle & versioning.** States: Draft → Proposed → In Review →
Approved (+ Deprecated). Every change creates a version with author, timestamp,
source (human edit / accepted proposal / accepted comment / accepted answer) and
diff. History is never overwritten; full evolution timeline (raw note → question
→ answer → requirement → comment → revision → approval) is visible per
requirement.

**REQ-08 — Priority.** Flexible dimensions (business value, urgency, customer
impact, risk, dependency, strategic importance) with a project-configurable
scheme; no hardcoded methodology.

**REQ-09 — Detail screen.** Sections as cards with per-section completeness,
sources panel (backward traceability), trace panel (questions, answers,
comments, prototype screens, criteria, reviews), inline comment threads, version
timeline, spec-chat slide-over.

*Acceptance:* a requirement with all sections filled scores 100% structural
completeness with a visible per-section breakdown; every version diff is
reconstructable; deleting is impossible (only Deprecated).

#### 6.5 `m-glossary` — Glossary, calculations & policy library

- **GLO-01** Business glossary: term, definition, synonyms, owner, status,
  usage links. AI must use glossary terminology in all generated text.
- **GLO-02** Calculation definitions (e.g. `Margin = Selling Price − Cost`):
  name, formula in business notation, inputs, worked example, used-by links.
- **GLO-03** Policy/rule library: reusable business policies referenced by
  multiple features (change once, see every affected feature).
- **GLO-04** Term consistency lint: flags spec text using undefined or
  conflicting terms (advisory).

*Acceptance:* renaming a glossary term shows every usage; a policy lists every
feature referencing it.

---

### Phase 2 — Intelligence

> Outcome: AI (via `claude -p`) turns raw knowledge into structured proposals,
> questions and register entries — always as suggestions, always governed.

#### 6.6 `m-ai-runtime` — Claude Code AI runtime & cost governance

Implements §4 as a product surface.

- **AIR-01** AI Job queue: every capability invocation is a job (visible status:
  queued/running/succeeded/failed), executed via `claude -p` per §4.1;
  concurrency limited (default 1) so cost stays predictable.
- **AIR-02** Capability registry with per-capability instruction template, output
  schema, default model (haiku/sonnet/opus mapped to job weight) and toggle.
- **AIR-03** AI Console screen: toggles (per §4.3), job history with duration,
  model, cost/tokens as reported by the CLI, outcome, and links to produced
  proposals; per-capability usage counts.
- **AIR-04** Guardrail (enforced in code, mirrored as governance item GG): AI
  jobs write only proposals/questions/register-suggestions — never canonical
  objects, approvals, or review verdicts.
- **AIR-05** Every AI output stores its **why** (source refs + reasoning summary)
  for on-demand display (§4.4).
- **AIR-06** Failure UX: a failed job explains what happened and offers retry;
  no partial silent writes.
- **AIR-07** Context bundles are reproducible: a job's exact input manifest is
  stored, so "what did the AI see?" is always answerable.

*Acceptance:* with all toggles OFF, zero `claude` invocations occur; every job
in history can answer model, inputs, outputs, why, and cost; a killed CLI
process leaves no half-written proposals.

#### 6.7 `m-governance` — Governance framework

Four distinct, user-manageable concepts — never hardcoded into prompts or code:

- **GOV-01 Governance Rules** — principles governing behaviour (e.g. "every
  requirement must have a clearly identified business owner"). Applied during
  discovery, questioning, synthesis, review and prototype generation.
- **GOV-02 Guardrails** — boundaries the AI/system must not violate (e.g. "never
  create a UI component outside the approved library"). On violation: flag,
  explain, and either block or require approval depending on severity
  (advisory / needs-approval / blocking).
- **GOV-03 Golden Paths** — preferred solutions to recurring problems (e.g. the
  STD-LIST pattern). AI prefers them; deviation requires stated reason.
- **GOV-04 Standards** — consistent conventions (e.g. approved date format).
- **GOV-05 Scoped precedence:** items exist at Global → Organization → Workspace
  → Product → Project → Module → Feature; more specific overrides/extends
  broader per an explicit precedence model shown in the UI ("effective
  governance" view for any node).
- **GOV-06 Live management:** a user adds a rule in-app in plain language (e.g.
  "from now on, every approval feature must define timeout and escalation");
  it immediately joins future context bundles — no master-prompt rewriting.
  Each item: statement, rationale, scope, severity, examples, status, author.
- **GOV-07 Methodology config:** discovery methodology (section sets, question
  categories, readiness checklist, scoring weights) is configurable per
  project — no single hardcoded PM methodology.
- **GOV-08 Component library registry:** the approved `chandra-ui` set
  (dropdown, autocomplete, date picker, search, filters, tables, pagination,
  modals, forms, cards, navigation, notifications, …) as governance data.
  Generated prototypes must map every element to a registered component.
- **GOV-09 Component change impact:** when a registered component changes,
  list affected prototypes/screens/specs/features and offer "update affected
  artefacts?" with a diff before applying.
- **GOV-10 Governance violations** appear on the health dashboard (§6.19).

*Acceptance:* adding a rule changes the very next AI job's context bundle;
effective-governance view correctly resolves precedence for any node; a
blocking guardrail demonstrably stops a violating prototype generation.

#### 6.8 `m-synthesis` — Synthesis engine

The explicit "make sense of everything new" action, at project/module/feature
scope.

- **SYN-01** Reads unprocessed captures + accepted answers + accepted comments
  in scope; removes obvious duplication; maps information to existing
  requirements.
- **SYN-02** Produces only **proposals**: update requirement / new requirement /
  merge candidates / new assumption / new risk / new question / new conflict —
  each with source links and why. Never touches canonical directly.
- **SYN-03** Detects and surfaces: contradictions (with both sides quoted),
  assumptions, missing information, uncertainty, affected workflows / personas /
  UI / rules / notifications / acceptance criteria.
- **SYN-04** **Change summary** per run, human-readable: N changed, N new, N
  conflicts, N questions resolved, N new questions, N screens affected, etc.
- **SYN-05** **Triage board:** Added · Changed · Removed · Conflicting ·
  Unresolved · Newly inferred. Per proposal: side-by-side diff vs canonical,
  sources, why; actions accept / edit-then-accept / reject / defer. Accepting
  creates a new requirement version citing the proposal.
- **SYN-06 Duplicate detection:** "these two requirements may be duplicates" —
  resolution is human: merge / keep both / mark intentionally different (the
  mark suppresses future flags).
- **SYN-07 Conflict detection:** contradictory statements (e.g. "only managers
  approve" vs "sales executives approve") surface as conflict records; never
  auto-resolved; tracked until a human closes them.
- **SYN-08 Impact analysis before acceptance:** accepting a major change first
  shows potential impact on other requirements, workflows, personas, screens,
  prototypes, notifications, acceptance criteria and review status; PM decides.
- **SYN-09** Each run records scope, input manifest, model, outcomes — and
  advances captures to "included in synthesis".

*Acceptance:* a synthesis run over 30 captures yields a triage board where every
proposal cites ≥1 source; rejecting all proposals leaves canonical byte-identical;
the change summary matches triage contents exactly.

#### 6.9 `m-questions` — Question engine

- **QST-01** On demand per feature: "generate N questions" — the most important
  *unanswered* questions given everything known; no filler questions to
  increase volume (each must state why it matters).
- **QST-02** Categories: Business, User, Workflow, Rule, Validation, Permission,
  UX, Exception, Notification, Reporting, Integration, Compliance, Operational.
  Priority per question. Users add/edit their own questions equally.
- **QST-03 Adaptive questioning:** when an answer introduces ambiguity or a new
  dependency, the engine may propose follow-ups (e.g. "only if the customer
  changes the design" → what constitutes a design change? does the quotation
  return to draft? is prior approval invalidated? who reapproves? is the
  customer notified? is pricing recalculated?). **Real-time follow-ups are a
  toggle (default OFF)** — otherwise follow-ups appear at next synthesis.
- **QST-04** Question lifecycle: Open → Sent → Answered → Accepted/Rejected →
  Closed; every question shows answered-by-whom/when and resulting
  requirement(s) (§7 traceability).
- **QST-05** Open Questions register view: priority, owner, stakeholder,
  due/target date, status, answer, affected requirements — visible until
  resolved.

*Acceptance:* generated questions never duplicate an already-answered question;
each links category, priority, and why; the adaptive example above produces
follow-ups only when the toggle is ON or at synthesis.

#### 6.10 `m-registers` — Discovery registers

Shared registers with consistent UX (standard lists, badges, trace links):

- **RGS-01 Assumptions** (`ASM`): assumption, source, author, date, confidence,
  status (Open / Confirmed / Rejected / **Converted to Requirement** — keeping
  original source), affected requirements.
- **RGS-02 Risks** (`RSK`): risk, probability, impact, owner, mitigation,
  affected requirements, status.
- **RGS-03 Decisions** (`DEC`): decision, alternatives considered, rationale,
  decision maker, date, affected requirements. **Alternatives & trade-offs:**
  Options A/B/C compared on benefits, disadvantages, cost, complexity, user
  impact, business impact — AI may compare, never auto-chooses.
- **RGS-04 Constraints** (`CON`): regulatory, operational, financial,
  organizational, UX, timing, customer-specific — included in every relevant AI
  context bundle so they influence discovery and synthesis.
- **RGS-05 Dependencies:** typed links — depends-on, conflicts-with,
  affected-by — between requirements/features, with a visual relationship graph.
- **RGS-06** Register entries can be created by humans directly or accepted from
  AI proposals; all carry sources.

*Acceptance:* converting an assumption to a requirement preserves the assumption
record + source chain; the dependency graph renders both directions of every
link.

---

### Phase 3 — Collaboration & Review

> Outcome: stakeholders answer, comment and formally review; scores make
> completeness, confidence and quality explainable.

#### 6.11 `m-questionnaires` — Questionnaire workspace & stakeholder portal

- **QNR-01** PM composes a questionnaire from open questions (filtered by
  stakeholder relevance), previews it, and sends a **tokenised magic link** —
  no stakeholder account. Link scope: exactly that questionnaire (+ optionally
  the feature summary for context). Links expire and are revocable.
- **QNR-02** Stakeholder portal (distinct lighter shell, §73): must state their
  name before answering; mobile-first; questions one-at-a-time or list;
  answer via text / mobile text / device voice-to-text (transcript stored; no
  audio retained); can skip, mark unsure, or comment.
- **QNR-03** Answers record question, respondent (stated name + link identity),
  timestamp, text, status. Partial progress saves; resume via same link.
- **QNR-04** PM triage per answer: review, edit/interpret, accept, reject,
  partially accept, and **push into requirement** (creates a proposal → on
  acceptance a requirement version citing the answer).
- **QNR-05** Adaptive follow-ups per §6.9 QST-03 (toggle): if ON, a follow-up
  may appear in-portal after an answer; if OFF, follow-ups queue for the PM.
- **QNR-06** Outstanding-response tracking: who hasn't answered, reminders
  (manual send; channel = copyable message or email if configured).

*Acceptance:* a stakeholder with only a link can answer everything on a phone
without login; every accepted answer is traceable from the requirement version
it produced back to the respondent.

#### 6.12 `m-comments` — Inline comments & push-to-requirement

Select-any-content commenting on PRD/spec views and desktop/mobile prototypes.

- **CMT-01** Comment records author, timestamp, exact location/context (artefact,
  anchor, quoted text), body, status (Open / Accepted / Rejected / Addressed),
  related requirement.
- **CMT-02 Anchor stability (design decision):** derived artefacts always emit
  stable anchors — every rendered block carries the canonical ID it derives
  from (`data-req="R-102"`, section key, prototype screen/element id). A comment
  anchors to (artefact-version, anchor-id, text-quote). On regeneration, anchors
  re-attach by ID first, then by text-quote fuzzy match; unmatched comments are
  flagged **orphaned — never lost** and listed for manual re-anchoring.
- **CMT-03 Push to Requirement:** PM reads → edits/interprets → accepts → pushes;
  this creates a proposal whose acceptance produces a requirement version citing
  the comment (comment → change traceability, §83).
- **CMT-04** Threads support replies and resolution; unresolved comment counts
  roll up to feature and dashboard.
- **CMT-05** Prototype comments pin to screen + UI element and stay linked to
  screen, element, and requirement (§67).

*Acceptance:* regenerating a spec view after 20 edits re-attaches ≥ every
ID-anchored comment; an orphaned comment remains readable with its original
quote and can be re-anchored in ≤ 2 interactions.

#### 6.13 `m-reviews` — Review workflow & approval matrix

- **REV-01** Explicit reviewer assignment per spec/feature (Reviewer A/B/C…);
  only assigned reviewers give formal review; everyone else read-only.
- **REV-02** A review captures completion score, confidence score, approval
  status, comments, requested changes. Outcomes: Approved · Approved with
  Comments · Changes Requested · Rejected · Not Reviewed.
- **REV-03 Approval matrix:** per scope, who must approve (required / optional /
  final) — e.g. Business Owner required, Sales Head required, Operations
  optional, CEO final. Sign-off blocked until required + final approvals exist.
- **REV-04 Consensus view:** show agreement, disagreement, unresolved review
  comments and confidence differences per reviewer — never hide disagreement
  behind an average.
- **REV-05** Reviewer completion tracking, pending-review lists, review
  deadlines and follow-up nudges.
- **REV-06** Reviews attach to a specific canonical version; if the requirement
  changes after review, the review is marked stale and the reviewer notified.

*Acceptance:* a feature with one "Changes Requested" can never show as approved;
consensus view lists each reviewer's scores side by side.

#### 6.14 `m-scores` — Completeness, confidence, quality & readiness

All scores are explainable; no mysterious percentages, ever.

- **SCR-01 Completeness** per requirement/feature: per-section percentages
  (e.g. Objective 100 · Workflow 90 · Rules 70 · Validation 80 · Permissions 60
  · Notifications 40 · Acceptance 30 → overall 72) with the contributing
  breakdown always shown. Weights come from methodology config (§6.7 GOV-07).
- **SCR-02 Confidence** is separate from completion (100% complete can be 60%
  confident). Sources: author confidence + each reviewer's confidence, retained
  individually; overall is computed but every individual score stays visible.
  Low-confidence reasons are typed: business uncertainty, UX uncertainty,
  ambiguity, stakeholder disagreement, missing information, other.
- **SCR-03 Quality score** (AI-assisted lint + heuristics): clarity,
  completeness, consistency, testability, traceability, ambiguity, stakeholder
  confidence — each dimension with its why (e.g. flagged vague phrases).
- **SCR-04 Knowledge vs document completeness:** shown separately — a beautiful
  document with open critical questions scores low on knowledge completeness
  (open questions, unconfirmed assumptions, unresolved conflicts count against
  it).
- **SCR-05 Feature readiness:** rollup (discovery %, questions %, rules %, UX %,
  acceptance %, reviews %) → READY / NOT READY with the exact blocking reasons.

*Acceptance:* clicking any score anywhere opens its breakdown; two requirements
with identical text but different open-question counts show different knowledge
completeness.

#### 6.15 `m-ai-reviewer` — AI reviewer & gap analysis

Advisory only; human approval remains authoritative.

- **AIR-10** Pre-human AI critique per requirement/feature: what's missing,
  ambiguous, contradictory with other requirements; hidden assumptions; missing
  edge cases; unclear validation; unclear permissions.
- **AIR-11 Missing-feature recommendations:** e.g. "quotation approval defined
  but no rejection workflow" — recommendations, never auto-requirements.
- **AIR-12 Gap analysis:** explicit "what have we not defined?" run against the
  methodology checklist + domain template + governance rules.
- **AIR-13 Business-rule validation:** verify documented workflows respect
  documented business rules; flag contradictions before sign-off (§71).
- **AIR-14 Coverage & orphans:** coverage view across requirements ↔ questions
  ↔ answers ↔ workflows ↔ criteria ↔ prototypes ↔ reviews; orphaned
  information (unlinked captures, answers, screens) is listed (§35, §85).
- **AIR-15** All outputs are proposals/recommendation cards with why + sources;
  dismissing one records who/when/why.

*Acceptance:* AI review of a feature missing exception handling flags it with a
pointer to the governance rule/template item that expects it.

#### 6.16 `m-spec-chat` — Spec chat

- **CHT-01** Chat against a selected spec scope (project/module/feature),
  answering from canonical + underlying sources only, with citations (IDs)
  linked in every answer. Example answers it must handle: "Is customer approval
  covered?" · "Where is the approval timeout defined?" · "Has John's comment
  been addressed?" · "What requirements are still incomplete?" · "Show all
  unresolved questions." · "Why does this requirement exist?"
- **CHT-02** Runs as `claude -p` sessions (`--resume` for follow-ups) over a
  scope context bundle; toggle ON/OFF (§4.3); each conversation logged as an
  AI job.
- **CHT-03** "I don't know / not defined" is a first-class answer, with an
  offer to create an open question from it.
- **CHT-04** Available as a slide-over on requirement/feature screens and as a
  full screen.

*Acceptance:* every factual answer carries ≥1 citation that navigates to the
cited object; asking about something undefined yields the not-defined answer +
question offer, not a hallucination.

---

### Phase 4 — Experience & Sign-off

> Outcome: stakeholders *see* the product (journeys, prototypes), walk scenarios,
> and formally sign off a complete business package.

#### 6.17 `m-prototypes` — Prototype Studio (AI-generated live prototypes)

- **PRT-01** From approved (or selected) requirements, generate **clickable
  prototypes as live code** via `claude -p`, constrained to the registered
  component library (chandra-ui / the house prototype shell). Every generated
  element must map to an approved component (guardrail GG; §52, §56).
- **PRT-02** Prototypes reflect workflow, personas, permissions, validation,
  states and navigation from canonical — a stakeholder can follow a complete
  business journey (§61, §63).
- **PRT-03 Desktop + mobile:** distinct experiences, not scaled clones; AI
  identifies mobile-specific behaviour and the PM confirms it (§62).
- **PRT-04 Traceability both ways:** each screen/element carries the requirement
  IDs that justify it (`data-req`); requirement detail lists its screens; an
  element with no justifying requirement is flagged **orphan UI** (§84–85).
- **PRT-05 Persona experience mode:** view the prototype as CEO / Sales /
  Operations / Reviewer / Approver…; only that persona's capabilities appear —
  same underlying prototype, role-gated (§70, §17).
- **PRT-06 Scenario simulation:** walk a named business scenario (e.g. "customer
  rejects design after commercial approval") — the prototype highlights the
  relevant flow path step by step (§69).
- **PRT-07 UX review (AI, advisory):** usability, consistency, discoverability,
  unnecessary complexity, accessibility, missing states, missing actions (§65).
- **PRT-08 Design alternatives:** for significant UX decisions, generate/compare
  Options A/B/C with rationale and trade-offs; chosen option recorded as a
  decision (DEC) (§66).
- **PRT-09** Prototype versions pin to canonical versions; stale badge when
  canonical moves; regeneration shows a screen-level diff and preserves comment
  anchors (§6.12).
- **PRT-10** Information architecture view: navigation, sections, hierarchy,
  grouping, discoverability — business-facing (§64).

*Acceptance:* generated prototype uses only registered components (violations
blocked & listed); toggling persona hides exactly the capabilities the
permissions sections deny; every screen shows its justifying requirement IDs.

#### 6.18 `m-journeys` — Journeys & process maps

- **JRN-01** Generate business user journeys from approved requirements (e.g.
  Customer Inquiry → Design Creation → Design Review → Customer Approval →
  Commercial Approval → Order Creation) — business-stakeholder readable (§58).
- **JRN-02** Business process maps: actors, actions, decisions, approvals,
  exceptions, outcomes — never technical architecture (§59).
- **JRN-03** Journey steps link to requirements and prototype screens; clicking
  a step navigates to either.
- **JRN-04** Journeys are derived artefacts: regenerate on demand, stale badge,
  human-editable labels with edits preserved across regeneration where steps
  still match.

*Acceptance:* every journey step resolves to ≥1 requirement; a journey renders
meaningfully for a non-technical reviewer (tested with the showcase mode).

#### 6.19 `m-dashboard` — Discovery health dashboard

- **DSH-01** Project health view: completeness, confidence, unresolved
  questions, risks, assumptions, conflicts, pending reviews, pending approvals,
  prototype readiness, governance violations, AI recommendations (§49).
- **DSH-02** No single opaque score — every tile expands to its reasons and
  navigates to the underlying list (§76).
- **DSH-03** Per-feature readiness table (SCR-05) with blocking reasons.
- **DSH-04** Trend over snapshots: is discovery converging (open items ↓,
  confidence ↑)?

*Acceptance:* every number on the dashboard is clickable and lands on the exact
underlying items.

#### 6.20 `m-signoff` — Readiness gate, sign-off & handover

- **SGN-01 Readiness gate checklist** before marking discovery complete:
  business objective · stakeholders · personas · workflow · exceptions ·
  business rules · field validations · permissions · notifications ·
  search/filter/sort/pagination · exports · acceptance criteria · reviews ·
  conflicts resolved · critical questions answered · prototype reviewed ·
  governance satisfied. Only when the gate passes does the system recommend
  **READY FOR NEXT STAGE** (§90). Checklist content comes from methodology
  config.
- **SGN-02 Business sign-off package** (`PKG`): requirements, workflows, rules,
  validations, permissions, prototypes, acceptance criteria, unresolved items,
  review status — **only approved material** in the final package (§68).
- **SGN-03 Final discovery package** structure (§99): executive summary,
  problem, objectives, stakeholders, personas, workflows, business rules,
  validations, permissions, states, exceptions, notifications, reports,
  search/filter/sort, exports, acceptance criteria, open questions, assumptions,
  risks, decisions, review comments, approval status, prototype, sign-off.
  Rendered in the house PRD style (self-contained HTML) + shareable.
- **SGN-04 Showcase mode:** presentation-friendly per feature — Problem → User →
  Journey → Prototype → Business Rules → Expected Outcome — no internal
  discovery complexity (§74).
- **SGN-05 Snapshots & versioning:** immutable discovery snapshots (`SNAP`) at
  will and at every package generation; never overwrite history; compare any
  two snapshots (§91).
- **SGN-06 Handover:** clean, business-focused package for the next
  design/engineering stage (which may be a separate Build Engine consuming this
  output) (§79).

*Acceptance:* a package generated while a required approval is missing is
impossible; package content provably equals approved canonical at its snapshot.

---

### Phase 5 — Knowledge & Reuse (roadmap)

#### 6.21 `m-knowledge` — Knowledge repository & reuse

- **KNW-01** All approved discovery knowledge becomes searchable product
  knowledge (§77).
- **KNW-02 Requirement reuse library:** approved requirements/patterns (e.g.
  "Standard Customer Approval Flow") reusable across projects with preserved
  traceability to origin (§44).
- **KNW-03 Cross-project search** for authorized users: "how was customer
  approval handled in previous projects?" (§45).
- **KNW-04 Domain templates:** per domain (Jewellery, Manufacturing, Sales, CRM,
  Inventory, Approvals) — terminology, workflows, rules, question sets,
  standards, golden paths — attached per project; improves questioning and
  completeness without restricting users and without contaminating unrelated
  projects (§46, §97).
- **KNW-05 Multi-project learning:** reused knowledge is labelled *known
  pattern* vs *new project-specific requirement*; never blindly copied (§98).

*Acceptance:* reusing a library requirement records source library + original
project; domain template content never appears in a project that didn't attach
it.

## 7. Traceability model

A single typed link graph over all entities. Core link types: `derived-from`,
`answers`, `asked-about`, `cites-source`, `caused-change`, `implements`
(screen→requirement), `justifies` (requirement→screen), `depends-on`,
`conflicts-with`, `affected-by`, `converted-to`, `supersedes`, `imported-from`, `edited-externally`, `reviewed`,
`approves`.

Guaranteed navigations (each is a UI affordance, not a query):

- Requirement → its sources (captures, answers, comments, decisions) and every
  version's cause. Example: `R-102 ← Customer Meeting 12 ← Reviewer Comment 27 ←
  Questionnaire Answer 14 ← Raw Note 32`.
- Question → answered/unanswered, by whom, when, resulting requirement(s).
- Accepted comment → the requirement change it caused.
- Requirement ↔ prototype screens (both directions; orphan UI flagged).
- Acceptance criterion → its requirement (mandatory parent).
- Assumption → converted requirement (with original preserved).
- Notification ↔ originating feature.

Links are never deleted, only superseded. The complete evolution chain (raw note
→ question → answer → requirement → comment → revision → approval) renders as a
timeline on every requirement (§78, §80–86).

## 8. Personas & permissions (of the engine itself)

| Persona | Access |
|---|---|
| **Owner/PM** | Everything in owned scope: capture, synthesize, triage, edit canonical, assign reviewers, generate artefacts, sign-off |
| **Contributor** | Capture, propose, comment; no canonical acceptance |
| **Reviewer** | Read scope + formal reviews, scores, comments |
| **Stakeholder** | Magic-link portal only: assigned questionnaires, shared views/prototypes; answer, comment, approve/request changes; must state name |
| **Observer** | Read-only |

Persona-specific *product* views (CEO/PM/BA/Sales/Operations/Reviewer/Approver/
QA/Observer) are derived views over the same canonical knowledge — never
duplicated requirements (§17).

## 9. Non-functional & experience requirements

- **Performance:** interactive < 1s on lists of 1k requirements; AI jobs queued
  with visible progress, never blocking the UI.
- **Reliability:** append-only stores for captures/versions/links; crash-safe AI
  job handling (no partial writes).
- **Security:** single-tenant; auth for internal users; magic links scoped,
  expiring, revocable; stakeholder data minimal (stated name).
- **Accessibility:** keyboard-first, focus states, contrast via house tokens.
- **Observability:** AI Console + audit trail of every canonical change.
- **Maintainability:** capability templates, governance and methodology as data;
  vertical-slice modules.

## 10. Stack & deployment (build note, prose)

Per the chandra-prd decisions: **Next.js + React + Tailwind on `chandra-ui`**,
house design tokens, light/dark theming. Single-node self-hosted deployment on
the owner's server (same nginx setup as existing aispec site) with **SQLite** as
the store (single-tenant scale) and the filesystem for capture attachments and
generated artefacts. The server has Claude Code installed and authenticated;
the app shells out to `claude -p` (§4). No external LLM API, no API keys.
Derived HTML artefacts (packages, prototypes) are written as self-contained
files servable by the same host. *(Data model details intentionally prose-level
here; schema design happens at build time and is not part of discovery output.)*

## 11. Build phasing & first vertical slice

Phases 1–5 as in §6. **First vertical slice (walking skeleton):** 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, then modules are
added in phase order. Every slice: understand → define UX → implement → test →
validate acceptance → update docs → next.

## 12. Brief coverage matrix

| Brief § | Covered in |
|---|---|
| 1–2 vision, philosophy | §1, §2 |
| 3 business boundary | §3.3, §6.20 |
| 4 canonical truth | §3.2 |
| 5 hierarchy | §6.2 |
| 6 inbox | §6.3 |
| 7 synthesis | §6.8 |
| 8–9 questions, adaptive | §6.9 |
| 10 questionnaire | §6.11 |
| 11 requirement structure | §6.4 REQ-01 |
| 12 field-level spec | §6.4 REQ-02 |
| 13 standard lists | §6.4 REQ-03 |
| 14 export spec | §6.4 REQ-04 |
| 15 notification catalog | §6.4 REQ-05 |
| 16 acceptance criteria | §6.4 REQ-06 |
| 17 persona views | §8, §6.17 PRT-05 |
| 18 review workflow | §6.13 |
| 19 confidence | §6.14 SCR-02 |
| 20 completeness | §6.14 SCR-01 |
| 21 inline comments | §6.12 |
| 22 spec chat | §6.16 |
| 23 AI cost governance | §4.3, §6.6 |
| 24 source traceability | §7 |
| 25–31 registers, decisions, alternatives | §6.10 |
| 32 prioritization | §6.4 REQ-08 |
| 33–34 duplicates, conflicts | §6.8 SYN-06/07 |
| 35 coverage | §6.15 AIR-14 |
| 36 approval matrix | §6.13 REV-03 |
| 37 quality score | §6.14 SCR-03 |
| 38 AI reviewer | §6.15 |
| 39 impact analysis | §6.8 SYN-08 |
| 40–42 glossary, calc, policies | §6.5 |
| 43 readiness | §6.14 SCR-05 |
| 44–46 reuse, cross-project, templates | §6.21 |
| 47 missing-feature recs | §6.15 AIR-11 |
| 48 knowledge completeness | §6.14 SCR-04 |
| 49 health dashboard | §6.19 |
| 50–57 governance + component library | §6.7 |
| 58–59 journeys, process maps | §6.18 |
| 60–67 prototypes, UX review, alternatives, prototype comments | §6.17, §6.12 |
| 68–70 sign-off, simulation, persona review | §6.20, §6.17 |
| 71 rule validation | §6.15 AIR-13 |
| 72 gap analysis | §6.15 AIR-12 |
| 73 customer workspace | §6.11 |
| 74–75 showcase, package | §6.20 |
| 76 health | §6.19 |
| 77–79 knowledge, history, handover | §6.21, §6.4 REQ-07, §6.20 |
| 80–86 traceability | §7 |
| 87–88 consensus, deadlines | §6.13 |
| 89 change impact | §6.8 SYN-08 |
| 90 readiness gate | §6.20 SGN-01 |
| 91 versioning | §6.20 SGN-05 |
| 92 change summary | §6.8 SYN-04 |
| 93–94 explainability, AI not authority | §4.4, §2 |
| 95–96 methodology, scoped governance | §6.7 |
| 97–98 domain knowledge, learning | §6.21 |
| 99 final package | §6.20 SGN-03 |
| Artefact import (bootstrap from existing doc/prototype) | §6.3B BRG-01–05 |
| External edit round-trip / "mark as fixed" | §6.3B BRG-06–11 |
| 100 ultimate principle | §1 |
| Experience principles | §6.1, §9 |
| Architecture principle (5 layers) | §3.1 |
| AI abstraction | §4.2 |

## 13. Decisions taken & open points

**Decided (owner):** single-tenant own use · Jewellery ERP first, domain-agnostic
core · stakeholders via magic link + stated name · prototypes as AI-generated
live code on chandra-ui · chandra-prd stack & house style · responsive web ·
async collaboration · **all AI via Claude Code `claude -p`, no API** · comment
anchors must survive regeneration (solved per §6.12 CMT-02) · **Artefact Bridge
(added 2026-08-29):** import an existing document/prototype by link or upload to
bootstrap a project, and an external round-trip — edit an artefact directly in
Claude Code outside the engine, bring it back, and "mark as fixed" to reconcile
canonical and resolve addressed comments (§6.3B).

**Open (non-blocking, defaults stated):**
1. Email sending for reminders/links — default: copyable links/messages first;
   SMTP later.
2. WhatsApp channel for questionnaires — default: out of v1; meta skill exists
   if wanted later.
3. Multi-user auth needs — default: simple local auth for owner + named
   collaborators; SSO out of scope.

---

*End of specification. Companion artefacts: `DISCOVERY_PRD.html` (illustrated,
review-friendly rendering of this spec) and `prototype/discovery-engine.html`
(clickable prototype of the engine itself, using Jewellery-ERP demo data).*