Tips and tricks

A short set of habits that keep a Piyaz project moving and the dependency graph trustworthy.

Size tasks to one session

A task should fit in one working session for one person. If it feels larger than 13 story points, split it. Small tasks make parallel work safe and status tracking meaningful.

Use the fields, not tags, for priority and size

Signal importance with the priority field (urgent, core, normal, backlog), not a tag. A typical 30-task project has only a handful of urgent tasks. Record size with the estimate field using Fibonacci points (1, 2, 3, 5, 8, 13); anything over 13 means split.

Write tasks an agent can act on

Title a task as a verb plus a noun. Keep the description to two to four sentences with concrete file paths or endpoints, not vague nouns. A task that names where the work happens is a task an agent can pick up cold.

Record decisions as choice plus why

A decision is the choice you made and the reason for it. Record it when you make it. Never invent a rationale you cannot cite. A shorter, true list beats a longer, fabricated one.

Ask the graph what to work on

Run the critical path analysis to find the longest dependency chain, the one that sets the project's minimum duration. Work the bottleneck first. The ready list tells you what you can start; the critical path tells you what matters most.

Keep the graph honest

After finishing a task, update the edges and descriptions it touches. A stale graph gives every later session bad information. Propagation is the work, not an afterthought.

Ground the agent before it acts

Tell the agent to read the task, explore the codebase, and check current library docs before it claims or plans. A task written a week ago may have drifted; have the agent validate the plan against what shipped and flag anything stale rather than trusting the text. Search and read first, no speculative decisions.

Truth is what shipped

The execution record and the PR body describe the merged diff, not the original plan. When the plan and the diff disagree, the diff wins, and the record is rewritten to match it. State specifics: the problem, the files, the decision. No narrative, no reference to "today."

Route the model to the job

Use the stronger model for review and reasoning, where a missed finding is expensive, and the cheaper tier for mechanical work. Composer does this for you per phase; when you drive a task by hand, ask for the stronger model on the parts that carry judgment.

Audit the graph periodically

Have the agent sweep the unfinished part of the graph against the live codebase and the PRs that shipped, so stale tasks do not pile up.

/piyaz:manage housekeeping on this project. Check the draft and plannable tasks
against the current codebase and the PRs that shipped, connect missing edges, and
prune what is already done.

Hand off cleanly between sessions

A good handoff names exact refs, the context depth to fetch, and the files to read first, so the next session begins from ground truth instead of a summary.

/piyaz create a handoff for MET-3 so the next session starts cold: which docs to
read, the task ref and the depth to fetch it at, and the files to read before
writing any code.