0
Kai Detmers
← Project index
Requirements engineering · AI workflow prototypeResearch prototype

ReqForge— from vague idea to testable system intent.

ReqForge explored a structured pipeline from initial product intent through clarifying questions into requirements, user stories, test cases and architecture artifacts. The useful lesson was not “LLMs can write user stories”; it was how quickly a multi-artifact workflow breaks when schemas and model contracts are treated as prompt details instead of product architecture.

How it evolved

Reconstructed from the 2025 commit history. The repository contains unusually candid commits such as “Not working”, “user Story broken” and “Broken schema”; I keep that failure progression because it is the most valuable engineering part of the case.

01
Start with artifact generation.

The early product proved that an idea could be expanded into requirements-related outputs and a usable project flow. At this stage prompts and UI were doing more coordination work than the domain model.

02
Add a questionnaire before generation.

A clarifying-question flow shifted the UI from “type one prompt and hope” toward requirement discovery. This is important because ambiguity should be surfaced before the system creates authoritative-looking artifacts.

03
Broaden the workflow — then pay the coupling cost.

Collaboration/multiplayer ideas, coding-machine concepts and more artifact types expanded the product surface. Each additional downstream artifact increased the number of assumptions that had to remain consistent.

04
Change model/workflow and expose schema fragility.

The late commit sequence is explicit: move to a new model → user story broken → not working → broken schema. The pipeline had hidden coupling between provider output, intermediate data and UI expectations.

05
Extract the architectural lesson.

Requirements artifacts need versioned contracts and repairable transformations. A modern successor should treat requirement, story and test-case schemas as first-class domain types, not as examples embedded inside prompts.

UI rationale

Conversation before documentThe system should first expose uncertainty through questions. Generating a polished specification too early creates false confidence and makes users less likely to correct assumptions.
Artifacts need visible lineageA user story should show which requirement it came from; a test should show which acceptance criteria it covers. Navigation should follow dependency, not just file type.
Generated does not mean finalEach artifact is a reviewable state with unresolved questions and repair actions. The UI should communicate completeness/confidence rather than presenting all generated text with equal authority.
One change should propagate deliberatelyIf a requirement changes, downstream stories/tests should be marked stale or regenerated with a visible diff — not silently replaced.

What I would build differently now

Intent→Capture problem, constraints, stakeholders and unresolved questions in a typed project context.
Requirement→Versioned schema with provenance, assumptions and status — not free-form model output.
Transform→Stories, tests and architecture are derived through explicit versioned transformations.
Validate→Schema validation and semantic checks happen before artifacts reach the UI/export layer.
Repair→Failures become targeted repair jobs with diffs, not full-pipeline retries.

Why keep this case

ReqForge is valuable because it shows an architectural dead end clearly. The project reached enough complexity for prompt-centric orchestration to fail. That failure directly motivates the contract-first, evaluation-heavy requirements systems I would build today.

Related