# Proposal Format Reference

Load this reference before returning a Workflow Code proposal. Define conceptual structure only;
leave concrete module and API mapping to `workflow-code-builder`.

## Output Shape

````md
Workflow Code proposal:

Implementation boundary:
- conceptual design only; `workflow-code-builder` will resolve modules and APIs from the installed official documentation
- proposed connections and Mermaid topology express desired behavior, not guaranteed Workflow Code support or compilability

Inputs:
- `document`: file, required

Flow:
1. `Extract invoice data`
   - responsibility: identify the relevant invoice fields
   - consumes: `document`
   - expected output: structured invoice fields
   - behavior required: semantic extraction from unstructured content
   - schema needed: yes

2. `Validate invoice fields`
   - responsibility: apply deterministic business rules
   - consumes: `Extract invoice data`
   - expected output: validated fields plus review status
   - behavior required: deterministic validation
   - schema needed: yes

3. `Review exceptions`
   - responsibility: investigate records that need judgment
   - consumes: exceptions from `Validate invoice fields`
   - expected output: corrected data and review notes
   - behavior required: investigation and review
   - schema needed: yes

Connections:
- `document` -> `Extract invoice data`: supplies the source content
- `Extract invoice data` -> `Validate invoice fields`: validates the extracted contract
- `Validate invoice fields` -> `Review exceptions`: sends only uncertain records for review

Expected final output:
- structured invoice data with validation and review results

```mermaid
flowchart TD
  document[/Input: document<br/>file, required/]

  extract[Stage: Extract invoice data]
  validate[Stage: Validate invoice fields]
  decision{Needs review?}
  review[Stage: Review exceptions]
  finalize[Stage: Finalize result]

  document --> extract
  extract --> validate
  validate --> decision
  decision -->|yes| review
  decision -->|no| finalize
  review --> finalize

  classDef input fill:#f6f8fa,stroke:#8c959f,stroke-dasharray:4 3,color:#24292f
  class document input
```

Assumptions:
- the document contains enough information for extraction
- deterministic rules identify which records need review

Open questions:
- Which fields and validation rules are mandatory?
````

## Proposal Discipline

- Include every literal heading from the template.
- Put one fenced Mermaid diagram after `Expected final output` and before `Assumptions`.
- Do not add a separate implementation or visual-sketch section.
- Keep each stage focused on one responsibility.
- Prefer one obvious input over speculative optional controls.
- Group related outputs unless the user supplied an exact schema.
- Put uncertainty in `Assumptions` or `Open questions`, not in invented API details.
- Do not use module, helper, option, or source-syntax names as conceptual labels.

## Mermaid Shape

- Start with `flowchart TD`.
- Declare inputs first with parallelograms.
- Label executable work as `Stage: <business responsibility>`.
- Use decision diamonds for conceptual routing when it materially explains the solution.
- Show iteration and aggregation conceptually when central to the request.
- Treat branches, decisions, iteration, fan-out, and fan-in as desired behavior for the builder to
  resolve, never as evidence of an installed or directly compilable Workflow Code topology.
- Declare edges after nodes and label important branch outcomes.
- Add the input class definition once.
- Keep the diagram to three to five main stages when possible.
- Never output Mermaid as plain text or include more than one Mermaid block.