How to use PAPI

The habits, the workflow, and the debugging moves that make PAPI pay off. For the mechanics of each tool call, read the Core Workflow — this page is about how to work with PAPI well.

1. What PAPI is for — and what it isn't

PAPI is for planned work. It keeps one plan — the vision, the decisions, and the progress — somewhere every session and every AI client can read it, so the work compounds instead of evaporating with the chat history.

Two failure modes are what it exists to prevent:

• Tracker mode. You build first and tick boxes later. The board drifts from reality, the next plan plans the wrong thing, and the decision trail becomes fiction.
• Ad-hoc mode. Work never routes through the cycle. Every session starts cold, rebuilds what already exists, and quietly contradicts a decision from last week.

Quick work is legitimate. A typo, a one-line config change, an urgent fix — just do it. Then record it with ad_hoc so it shows up in cycle history and metrics. Unrecorded work is invisible work: it doesn't count toward velocity, and the next plan cannot see it.

2. The session loop

Every session opens the same way.

1. orient first. Before you read files, before git status, before anything else. One call returns your cycle, what's in flight, and the recommended next action.
2. Follow the recommended next action. It tells you whether to build, review, release, or plan — so you never have to guess what to do next.
3. Pick work deliberately. build_list shows what's ready to build, review_list shows what's waiting for sign-off, and plan runs when the cycle is empty.
4. One task at a time. Finish it, record it, then move on. Parallel tasks are how scope drifts.

After your client compacts the conversation, re-orient. Do not resume from guesswork. Run orient again, reload where you are, and — this is the important one — never re-build a task that is already In Review or Done. Re-building reviewed work is one of the most common and most expensive mistakes.

3. Working a cycle end to end

A cycle is setup → plan → build → review → release → strategy review, then repeat.

• Setup (once per project) writes the Product Brief, the first Active Decisions, and the project conventions into your client's instruction file.
• Plan selects tasks from the backlog and writes a BUILD HANDOFF for each. Size the cycle from delivered velocity in recent cycles, not from optimism — the trend that orient reports is the honest number.
• Build implements one task from its handoff.
• Review is the human gate: accept, request changes, or reject.
• Release cuts a version when every cycle task is Done.
• Strategy review runs every 5 cycles and is where the compounding happens — it reads velocity, estimation accuracy, and the decision trail, and recommends direction changes.

The backlog is the steering wheel, not a dumping ground. What you file, prioritise, and annotate is what the next plan picks up. If you want the project to move a certain way, put it in the backlog and say so.

4. Building well

• Build exactly the handoff. The BUILD HANDOFF is the contract: scope, out-of-scope, acceptance criteria, files likely touched. "While I'm here" extras are how a small task becomes an unreviewable one.
• Branching. In-cycle tasks in the same module share one branch — feat/cycle-N-<module> — with one commit per task, so history stays traceable and the module merges as a unit.
• Gestalt pre-build check. On the first task of a multi-task cycle, read all the cycle's handoffs together before writing code. Shared files, sequencing, and a producer/consumer ordering are invisible when you read handoffs one at a time.
• Verify before you claim done. Run the tests, the linter, and the typechecker. Then exercise the change the way a user would — not just the unit test. "It compiles" is not "it works".
• Report the build honestly. Effort against estimate, surprises, the dead ends you ruled out, and issues you found outside scope. This record is what later cycles are planned from; a vague report makes every future plan worse.
• Don't over-engineer. No unasked-for features, no speculative abstractions, no dependencies the current task doesn't need.

5. Keeping scope honest

• Scope creep mid-build? Park it. File it with idea for the next plan instead of building it now. The current task stays reviewable and the idea is not lost.
• Found a bug outside your task? File it, don't fix it. Fixing it in-flight widens the diff and mixes concerns. File it with a severity and keep moving.
• Did quick work outside the cycle? Record it. ad_hoc turns it into a task plus a build report so it lands in history.
• Never silently edit the plan. If the plan is wrong, say so and re-plan — don't quietly build something different while the board claims otherwise.

6. The compounding layer

• Active Decisions record what was chosen, what was tried and dropped, and why — with a confidence level that moves as evidence arrives. Supersede a decision rather than overwriting it; the history is the value.
• A contradiction is a decision, not a veto. If new work cuts against a live Active Decision, that is the owner's call to make. Surface it and let the decision be tested — don't quietly shelve the work because it looks like it conflicts.
• The idea pipeline is your backlog intake — features, bugs, research, and big ideas. File early and often; it costs nothing and nothing gets lost.
• The doc registry keeps the project's durable documents discoverable, so planning and reviews can find them.
• Board reconciliation keeps the board matching reality. Run it when things feel out of sync.

7. Debugging and troubleshooting

"PAPI isn't working" — start here.

• The tools aren't in my list. MCP clients snapshot the tool list when a conversation starts. A server added mid-conversation is invisible to that conversation — this is not a failed install. Start a new conversation (and pick the project again if you're asked), then call orient. Some clients can reload MCP within a session; try that first if yours can.
• orient fails or errors. Check the MCP connection first: is your server config pointing at the right endpoint, and is the process healthy? Fix the transport before debugging anything else.
• It's showing the wrong project. Stop — every write would land on the wrong board. Check the project id in your client configuration and reconnect.
• A task looks stuck. Check its status before acting:
  • Backlog — not started. But check whether a feat/task-NNN branch already exists with commits; if it does, fix that rather than rebuilding.
  • In Progress — a build started. Read the branch and the existing changes before writing anything.
  • In Review — already built. Run review_list then review_submit. Never re-build it.
  • Done — finished. Leave it alone.
• The context was compressed or I lost the thread. Re-run orient, check your todo list, and continue where you left off. Don't restart the cycle.
• PAPI itself is broken (a tool error, a handoff problem, a cycle that won't advance)? Report it — PAPI bugs go upstream so they can be fixed. A bug in your project goes on your own board.

8. Anti-patterns