Flow
Contents · The Flow Book

Start here

The Flow Book1. Your first run2. Let the outside answer3. Keep the original answer

Build the decision

4. Give the program an input5. Name the work6. Give values a shape

Build the workflow

7. Decide what failure means8. Put the decision in its own file9. Put the pieces together

Go further

10. Work on several things11. Leave room for an answer12. Take Flow into an application

Build an application

13. Investigate a real question14. Challenge: diagnose and extend
Language reference ↗
The Flow Book / Build an application

Challenge: diagnose and extend

Investigate a missing answer without weakening the publication decision. Use the project workbook, your editor and the CLI. Allow about 10–15 minutes after finishing the guided steps; stop to inspect a confusing record rather than racing the clock.

Your task

A colleague needs an additional answer about operational recovery. They received a brief with convincing claims and expected it to publish. You must explain why the outcome is correct or identify a defect, propose a repair at its owner, and demonstrate what changes when the requirement changes.

Use fresh directories for every new run. Keep completed records intact. This is a diagnosis exercise using declared teaching replies, not an evaluation of live research ability.

Before you run

Write three predictions:

  1. What outcome should missing-topic produce if the assessor reports no gaps?
  2. What should happen to a claim whose exact quotation is absent from its retained source?
  3. What should replay do after you change the requirements for a new investigation?

Do not inspect the guided chapter's explanations until you have recorded these predictions.

Collect your evidence

python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case missing-topic --directory /tmp/flow-challenge-missing
python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case quote-mismatch --directory /tmp/flow-challenge-quote
python3 examples/research/workbook.py start \
  --case complete --requirements-json examples/research/workbook-recovery-requirements.json \
  --directory /tmp/flow-challenge-recovery

The third command supplies a separate explicit card file retaining both original cards and adding the recovery obligation. Inspect each printed brief and its history. Use workbook.py history --directory DIR and workbook.py replay --directory DIR; add --json for structured output. Inspect calls.jsonl for complete application arguments and result.json for retained source text when history summaries abbreviate values. Compare calls.jsonl and store/effects.jsonl line counts before and after replay; absence of the effect file means no workbook publication was recorded. Reference a specific Tool reply, source excerpt and decision in your diagnosis. A label such as “the model failed” is insufficient: which value or field failed which check, and which layer owns it?

Open examples/research/main.flow and tools.flow. Find the expression that determines publication and the expressions that admit supported evidence and requirement resolutions. Explain how a true finding can coexist with an Unresolved requirement, and why a topic label alone cannot finish it. Explain whether your proposed repair belongs in requested inputs, source acquisition, draft/assessment replies or the Flow controller. Do not delete a coverage check merely to obtain a published result.

For a source-code variation, choose one additional deterministic condition that a claim must satisfy before it counts. Write its expected behavior for an accepted and a rejected claim before editing the controller. Check the modified program with python3 examples/research/workbook.py check, then run your chosen case in a fresh directory. If the teaching cases never exercise the condition, state that the check established typing only and propose a specific additional test. Restore only your own deliberate edit after the exercise; do not reset someone else's working tree.

What to submit

Keep a short note beside your new run directories:

Evidence A convincing answer contains
Prediction Original expectations, recorded before outcomes, and an explanation of any disagreement.
Fault location and repair A concrete reply or source field, its owning layer, and a repair that preserves the requested answer and evidence checks.
Variation A new declared requirement or controller condition, its expected effect, and a fresh run or an explicit untested case.
Boundary Separate model proposals, Flow's decision, host responsibilities and semantic source review.
Replay effects The replay verdict and observed call/publication counts before and after; distinguish replay from fresh research.

A successful diagnosis may retain an incomplete outcome. The goal is to explain what evidence is absent and how to obtain or test it, rather than make every case say Published.

Check your reasoning afterwards

Return to the guided project and compare its missing-topic and quote-mismatch explanations with your note. If you still cannot name the rejected condition, trace the candidate claim from draft, through assess, into the admission filter. If a replay verdict matches but you have not inspected the effect records, your replay evidence is unfinished.

For an optional live extension, use the linked application recipe. Require a distinct answer for each API or criterion and manually review every admitted claim against its saved source. Treat provider/version differences as evidence to resolve, not labels to erase.

Exact owners: evaluation, typed Tools, semantic history and execution, replay and resume.