flatbreadlabs/flatbread/effort-modeling

Effort modeling

Use this discipline while a plan or design is being shaped. Store planning records in Proof. Keep project terms in a glossary such as CONTEXT.md or docs/glossary.md.

Resume before asking

From the project root, use the proof skill's bounded reads:

1. flatbread proof list --status active
2. For the relevant Effort, inspect open Issues and blocking Decisions.
3. Read a record or digest when a prior conclusion affects the question.

Look up facts in code instead of asking. Put decisions to the user; do not answer them autonomously.

During the grill

Ask one question at a time. Offer a recommendation, wait for the user's answer, and resolve prerequisite choices before dependent ones.

• Challenge a term that conflicts with the glossary.
• Sharpen vague or overloaded terms.
• Use concrete edge cases to test relationships and scope.
• Compare a claim about behavior with the code and surface contradictions.
• Update the relevant project glossary when vocabulary resolves. Keep it free

of implementation details and planning rationale.

Journal the right speech act

Use flatbread proof write for the current Effort, following Proof reference:

• Finding — evidence about code, users, or runtime behavior.
• Issue — a question, defect, gap, or blocker needing attention.
• Constraint — a sticky hard or soft boundary.
• Risk — a prospective negative outcome with likelihood and severity.
• Decision — a proposed or accepted commitment among alternatives.

Two kinds of links

Use these links for different purposes:

• `cites` — links a record to a Citation for an external URL,

document, or saved source. Records never cite Blobs directly.

• `derives_from` — links a record to the Findings, Constraints, Risks,

and Issues that informed it.

A Decision typically uses derives_from for project reasoning and cites for outside sources.

External evidence (URL or longform)

When a Finding, Issue, Decision, Constraint, or Risk rests on an external source, create a Citation instead of copying the source into the record body:

1. `WriteBlob` — only when you need to save large or non-text content

(markdown, JSON, an image, and so on).

1. `WriteCitation` — body is often the URL string; pass optional blob and

role when needed.

1. Create the record — pass cites: ["<cit-id>"] when creating the

Finding, Issue, Decision, Constraint, or Risk. You cannot add a citation later, so create the Citation first.

Record a Decision when it is hard to reverse, surprising without context, and the result of a real trade-off. Create it as proposed while the user is still deciding; call AcceptDecision only after they commit. It rejects only proposals tied to the same question Issue, even after it closes. Use rejects to name other alternatives and dryRun: true to review the planned changes first.

Use the long-form body template in DECISION-BODY.md when the rationale would otherwise be lost. The body is the durable explanation; do not create an ADR alongside it.

Finish

Capture accepted Decisions, unresolved Issues, and material Findings before ending the session. For an immediate verification read, use the generation returned by the mutation with --strict-min-generation.