Representation-Form Recommendation — idea→documentation pipeline#

Status: recommendation + owner-decision request. This memo does NOT finalize the form of the tool or any architecture/source-of-truth decision — that is reserved for the owner. Inputs: state/research/methodology-landscape.md (d1) and state/research/stage-chain-matrix.md (d2).

Purpose#

Our tool must carry a raw input (bare idea OR worked-out business process) through ordered stages (idea → business model & actors → use-cases/user-stories → UX → UI/design → frontend → backend) where stage N's output is stage N+1's required input, the AI detects missing info and asks the right questions before advancing, and the final build stays faithful to the original intent. The open question (the owner's "next question") is: in what FORM do we collect and represent this pipeline? Below are the candidate forms, evaluated against our three hard requirements.

Evaluation criteria (our hard requirements)#

Chaining — can the form mechanically express that stage N+1 requires specific upstream artifacts/fields, and refuse/flag when they are absent?
Machine-checkable completeness — can the system decide on its own "this artifact is done enough to advance" vs "ask a gap question", without a human judging prose?
Intent-faithfulness — can every downstream element be traced back to the upstream intent/answer it came from, so drift is detectable (and upstream changes flag stale downstream)?

Secondary: authoring effort/UX, build complexity, flexibility for the two entry points and for iteration (not pure waterfall).

Candidate forms#

A. Typed artifact-schema chain#

Each stage is a structured template (schema) with required/optional fields, validation rules, and declared dependencies on upstream fields/artifacts.

Chaining: strong — a stage schema explicitly declares requires: [upstream artifact/field]; the engine blocks/flags on missing inputs.
Completeness: strong — "done enough" = required fields present + validators pass; this is exactly where the AI's gap-questions attach (one unfilled required field = one question).
Faithfulness: medium→strong if fields carry provenance (see C).
Cost/UX: medium build; authoring can feel form-heavy unless free-text is AI-structured behind the scenes.

B. Document-centric with checklists#

Each stage is a prose document from a template; completeness enforced by a Definition-of-Ready/Done-style checklist (as in agile practice, see d1).

Chaining: weak — "use the previous doc" is convention, not enforced.
Completeness: soft — a checklist is judged (by human or AI reading prose), not mechanically verified; prone to "looks done" drift.
Faithfulness: weak — no structural link between a sentence here and its origin there.
Cost/UX: lowest build, most familiar to author; flexible but least rigorous — closest to "AI generates a plausible doc", which is exactly the drift we are trying to prevent.

C. Graph / traceability model#

Artifacts and their elements are nodes; edges are typed relations (derived-from, satisfies, traces-to) — a requirements-traceability matrix fused with a knowledge graph.

Chaining: strong — dependencies are first-class edges.
Completeness: strong for coverage checks ("every use-case traces to an actor and a business goal").
Faithfulness: strongest — full bidirectional traceability; an upstream change instantly marks every downstream node stale.
Cost/UX: highest build and highest authoring burden; overkill as a standalone v1 and hard to present to a non-technical author.

Ranked recommendation#

Recommended: a hybrid with A as the spine — "typed artifact-schema chain with provenance links, rendered as readable documents."

A (typed schemas) is the backbone — it is the only form that makes completeness and chaining mechanical (criteria 1 & 2), which is what lets the AI reliably decide "ask vs advance".
Borrow B's rendering — every structured artifact renders to a human-readable document view, so authoring/reading stays natural and the output is shareable without exposing raw fields.
Borrow C's edges as a lightweight provenance layer — each field/answer carries a link to the upstream field it derives from. We get criterion 3 (faithfulness + stale-detection) without building a full graph product up front. Start with provenance only on the load-bearing links; promote to a fuller graph later only if a real need recurs.

Rationale vs the alternatives: pure B fails criteria 1-3 and reproduces the "AI hallucinates a nice doc" problem; pure C is the most correct but too heavy for v1 and for non-technical authoring. The hybrid gets A's enforceability and C's traceability at B's readability, and can be narrowed to a few stages first.

Open questions for the owner (the FORM + how the service works)#

These are genuine goal/value and architecture forks — I am NOT deciding them:

Authoring surface (UX fork): should the author fill structured fields directly (schema-first), or write free text that the AI structures into the schema behind the scenes? (Trade-off: rigor/transparency vs. natural feel.)
Gate strictness (goal/value fork): hard-block advancing until completeness is met, or allow advancing with flagged gaps (lean/iterative)? This is rigor-vs-speed and is yours to set.
v1 scope: support the full chain (stages 0-6) first, or prove the mechanic on the front stages (idea → use-cases, 0-2) before extending?
Build vs assemble: a custom app, or assemble on existing tools (structured docs / Notion / Linear) plus an AI layer?
Runtime/scope confirmation: internal/single-user only? persistence and where the source-of-truth lives?

Deliverables produced in this research milestone#

state/research/methodology-landscape.md — grounded survey, 7 areas, ~35 methodology/artifact subsections (each with input/output/completeness), ~60 sources.
state/research/stage-chain-matrix.md — our pipeline mapped stage-by-stage: required inputs, output artifacts, governing standards, completeness, ≥3 gap-questions per stage, ordering-disagreements, two traced entry points.
state/research/representation-recommendation.md — this memo.