# Effort Modeling

> Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into the Flatbread Proof. Use when a plan needs durable reasoning instead of ADRs.

- **Type:** Skill
- **Install:** `agentstack add skill-flatbreadlabs-flatbread-effort-modeling`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [FlatbreadLabs](https://agentstack.voostack.com/s/flatbreadlabs)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [FlatbreadLabs](https://github.com/FlatbreadLabs)
- **Source:** https://github.com/FlatbreadLabs/flatbread/tree/main/packages/proof/skills/effort-modeling

## Install

```sh
agentstack add skill-flatbreadlabs-flatbread-effort-modeling
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Effort modeling

Use this discipline while a plan or design is being shaped. Store planning
records in the 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
[the Proof reference](../proof/reference.md):

- **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).
2. **`WriteCitation`** — body is often the URL string; pass optional `blob` and
   `role` when needed.
3. **Create the record** — pass `cites: [""]` 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. Always pass
`"rejectSiblings": false` unless deliberately closing every competing proposal.

Use the long-form body template in [DECISION-BODY.md](./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`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [FlatbreadLabs](https://github.com/FlatbreadLabs)
- **Source:** [FlatbreadLabs/flatbread](https://github.com/FlatbreadLabs/flatbread)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-flatbreadlabs-flatbread-effort-modeling
- Seller: https://agentstack.voostack.com/s/flatbreadlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.