Clarify Requirements

For anyone whose tasks are coming back wrong, and for anyone writing one before it runs. Agents succeed or fail on the quality of their context, and Cat Factory works requirements at two levels:

1. A per-task clarification loop: the requirements reviewer makes one block unambiguous before any code is generated.
2. A service-level prescriptive spec: the Spec Writer aggregates every task's clarified requirements into a unified, in-repo spec/ document (plus Gherkin acceptance scenarios) that every later agent builds against.

Why this matters

A vague task produces vague code. Rather than discovering misunderstandings in the pull request, Cat Factory front-loads the clarification with a dedicated reviewer agent that inspects a block and reports what's missing.

Sources of requirements

A block's requirements can come from:

• A description you write directly on the block.
• Linked external sources: Jira or GitHub issues, plus Confluence, Notion, or GitHub repo documents, imported and expanded into the block's context. See Issue & Document Sources.

Brainstorming a direction first

When a task starts as a rough idea rather than a written brief, an optional Requirements brainstorm step runs ahead of the reviewer. Instead of expecting the requirements upfront, it proposes options as cards, each with explicit trade-offs, and lets you converge on a direction. In its window you choose an option, steer it with a comment, or dismiss it, then incorporate your choice and re-run for a fresh round. The direction you settle on becomes the subject the reviewer then clarifies, so brainstorming feeds straight into the review loop.

There is a matching Architecture brainstorm for exploring approaches before the Architect (see Choose and Edit a Pipeline → Anatomy of a pipeline). Neither ships in a build preset: add the one you want to a cloned pipeline. Each is a human gate, so it only runs when you opt in and are present to steer it.

The reviewer agent

The reviewer is an inline (no-container) agent. It analyzes the description and linked context and raises findings, each tagged with a category and a severity (low, medium, or high):

The reviewer runs as the first gate step when a task's pipeline includes it. It opens a dedicated review window, and the findings are persisted so you can work through them over several sittings. If the task names a responsible product person, they get the "findings raised" notification flagged to them directly; otherwise it goes to the task's creator.

The review stays on the product layer

The reviewer, the incorporation editor, and the Requirement Writer are all confined to the product and business layer. A technical design question is dropped outright rather than raised at a low severity, because it asks a product owner something they cannot answer, buries the questions only they can, and pre-empts the Architect and Researcher, which settle the technical layer later with the repository and the in-repo spec in hand.

For purely technical work the expected outcome is no findings at all. An empty review is the reviewer working, not the reviewer failing.

The review loop

Requirements review is iterative. Each round:

1. The reviewer raises its findings.
2. You answer or dismiss each one in the review window.
3. An incorporation companion folds your answers into one standard-format requirements document.
4. The reviewer re-reviews that document and either converges or raises a fresh round.

The cycle repeats until the reviewer is satisfied (or every remaining finding is dismissed). If a merge of your answers comes out wrong, you can redo it with a comment instead of accepting it.

Findings are grouped by whose court the ball is in: needs a reaction first, then waiting on the Writer, then already handled, with severity ordering within each group. On a long review you never scroll past answered cards to find what is still on you. The order is pinned while your cursor is inside a finding's text box, since an answer auto-saves on blur and re-sorting at that moment would slide the card out from under you.

Answering is low-friction: each answer auto-saves as you move off the field (there is no Save button), so a half-finished review is never lost. Your typed answers are flushed before any other action and preserved across background work, so they are still there when you come back.

Each finding carries an Answer / Dismiss / Recommend selector. Answer takes your typed response and marks the finding You answered. Dismiss drops it. Recommend asks the Requirement Writer to draft a grounded suggestion; anything you type alongside it is treated as guidance that steers the recommendation, shown on screen but not saved as the answer.

Auto-recommended answers

The reviewer sorts every finding into one of two buckets as it raises it:

• Answerable from best practice or context: findings a confident, defensible answer follows from universal engineering or product best practice, or that the provided context already settles. Cat Factory drafts a grounded recommendation and auto-accepts it as the finding's default answer, labelled Recommended default — keep it, edit it, or dismiss the finding. You stay in control: edit it, leave it, or dismiss the finding. When a best-practice prompt fragment settles it, the answer carries a Current standard: {title} badge.
• Needs a business, product, or domain decision: findings the engine will not guess at. These are left blank and flagged Needs your input, so only the calls that are genuinely yours pause you.

Auto-recommendation runs on every review round, and because it pre-answers the mechanical findings, it suppresses the "recommendations to review" notification for those. It is on by default, controlled per pipeline as a toggle on the requirements-review step in the pipeline builder: turn it off to answer every finding yourself.

Requesting a recommendation yourself

For a finding left to you, choose Recommend to have the Requirement Writer draft a grounded suggestion. It grounds each one in this order:

1. The service's best-practice prompt fragments (your team/org standards), flagged as the current standard when one settles the finding.
2. The in-repo spec/ and tech-spec/ documents.
3. Web search, for what the project material leaves open.

Recommendations run in the background, like every other review action, and render inline in the finding's own card: a "Generating a grounded suggestion…" spinner while the Writer works, then the ready suggestion in place. Each finding in a batch can carry its own steering note. The task card shows a Recommending… badge and the review's stats rail keeps a persistent Recommendations summary (how many are generating, how many are ready), visible even while you read the incorporated document. All of it is server-driven, so it survives closing the window, and you get a notification when the batch is ready. You can request recommendations whenever the review is editable, including a merged review you are reworking.

Recommendations are not AI-reviewed: you decide. For each ready suggestion you can Accept it (it becomes the finding's answer, folded into the next incorporation), Reject it (the finding reopens so you answer it manually), or Re-request it with a note to steer a fresh draft.

Incorporation and re-review run in the background. After you click "Incorporate answers" you go straight back to the board, and the task card shows which stage is running ("Incorporating answers…" then "Re-reviewing…") in place of an approval badge, since no action is needed until the reviewer comes back. You're summoned again only if the re-review raises fresh findings or hits the iteration cap; a converged round just advances the pipeline. (If you dismissed everything and left nothing to fold in, the round settles with no LLM call at all.)

Two per-task knobs on the risk policy tune the loop:

• maxRequirementIterations (default 3): how many reviewer passes run before the loop stops and asks you to choose one more round, proceed anyway, or stop and reset the task.
• maxRequirementConcernAllowed (default none): findings at or below this severity are recorded but auto-advance the run, with no human gate and the companion skipped, so only the findings that matter to you pause the run.

The unified in-repo spec

Where the reviewer clarifies one task at a time, the Spec Writer agent produces the durable, prescriptive spec for the whole service. It is the mirror image of a blueprint: a blueprint is descriptive ("what the code is"), while the spec is prescriptive ("what must be true").

The Spec Writer runs before the Architect when a pipeline carries it (and standalone via the Write spec pipeline). Every task gets a shared work branch created up front, so the spec lands on that branch first and the spec-aware Architect designs against it, rather than the spec being written only after the design is settled. The writer aggregates the clarified requirements of every task under the service frame and commits a spec/ folder, sharded by module → feature so two task branches editing different features never collide on merge:

Each module (a business domain) holds feature groups, and each group nests its own requirements and rules, so a group's file changes only when that group changes. There is no monolithic spec.json and no version.json: change detection is per file, and re-runs reuse the closest existing module/feature rather than spawning near-duplicates.

Each requirement carries a MoSCoW priority (must, should, or could), a kind (functional, non-functional, or constraint), an implementation state, provenance back to the board task(s) it came from, and structured Given/When/Then acceptance criteria.

The implementation state answers the one question a priority cannot: whether the service is actually known to honour the requirement. Aspirational means agreed but not yet observed; established means a tester observed it hold. An aspirational requirement's Gherkin scenarios carry an @aspirational tag, the build and test prompts read the state, and a pull request's verification report maps requirements to the evidence for them. Those criteria seed the Gherkin scenarios in a two-pass flow: the Spec Writer seeds the .feature files, the Acceptance Author agent polishes them, and the Acceptance Test Author agent turns each scenario into a runnable test. Re-runs rewrite the canonical files but never clobber the polished features.

The spec is not human-gated. Instead of pausing for your approval, the Spec Writer's companion, the Spec Reviewer, rates the spec (especially its acceptance-scenario coverage) and loops the writer back with the feedback folded in until the spec clears the bar. Every container agent reads the in-repo spec as context, and the engine strictly validates any returned document before ingesting it. The in-repo files are the source of truth.

Business specs vs. technical tasks

The spec captures business requirements, so the Spec Writer only writes one when a task has business behaviour to specify. A purely technical task (a refactor, a dependency bump, plumbing) produces no business requirements, and the writer commits nothing for it rather than inventing filler; the implementer then treats the task description as primary and the spec as a regression reference.

Each task carries a technical label in its inspector with three states: Unset (auto-detect) lets the engine infer it, while Technical and Business are authoritative choices the engine never overrides. Set it explicitly when you want to force the call (mark a clearly technical task Technical to skip business-spec work, or mark a misclassified one Business to ensure it gets a spec).

Viewing the spec

Open View Requirements from a service's inspector to browse the committed spec in a structured window: modules, then feature groups, then each requirement with its Given/When/Then criteria, plus a toggle to read the rendered Gherkin scenarios. Every requirement is badged with its implementation state, each group carries a rollup, the overview shows a service-wide rollup, and a three-way filter narrows the list to aspirational or established requirements. The window reads the spec from the repo's default branch, so it shows an empty state (rather than an error) on a service with no spec yet or no connected repository.

Recommended flow

Write/​link context  →  Run reviewer  →  Answer findings  →  Incorporate  →  Spec Writer aggregates  →  Ready to build

Next: turn a ready task into code with Run a Pipeline.