Execution Records

An execution record is a 3-5 sentence summary of what was built during a task's implementation, stored in the task.executionRecord field (see lib/db/schema.ts:61). It captures the outcome -- function names, file paths, endpoints, patterns used -- so that downstream tasks have concrete context about the work that was done.

What They Capture

When a task is marked as done, three fields should be recorded:

Example

executionRecord: "Built the MCP doc generator at scripts/generate-docs.ts.
Uses a mock MCP server pattern to capture tool registrations without
database connections. Walks Zod v4 _def internals to extract field
types and descriptions. Outputs one .mdx per tool plus meta.json."

decisions:
- "Mock server instead of source parsing — avoids regex fragility, gets exact Zod schemas"
- "Zod _def introspection instead of zod-to-json-schema — zero new dependencies"

files:
- scripts/generate-docs.ts
- package.json

How They Propagate

Execution records feed into the context network through the agent and planning context depths. When an agent requests context for a task at depth='agent', Piyaz follows depends_on edges recursively (via getDependencyChain in lib/graph/traversal.ts:55) and includes the execution records of upstream tasks.

Task A (done, has execution record)
  ▲
  │ depends_on
  │
Task B (in_progress, requesting agent context)

When the agent working on Task B calls piyaz_context depth='agent', it receives:

• Task B's description, implementation plan, and acceptance criteria.
• Task A's execution record and edge notes explaining why B depends on A.

This means the agent starts implementation already knowing what was built upstream, what decisions were made, and which files were touched -- without any manual briefing.

Multi-Hop Propagation

Both the agent and planning context depths follow dependency chains up to 2 hops deep. If Task C depends on Task B, which depends on Task A:

Task A (done) → Task B (done) → Task C (in_progress)

Task C's agent context includes execution records from both A and B, ordered by depth. The planning context includes execution records only from done prerequisites (useful for writing plans that account for what's already built). This keeps the full decision trail intact even across long dependency chains.

Decisions vs. Execution Records

Decisions are individual technical choices with rationale. They're stored as a structured array and appear in working context views.

Execution records are narrative summaries of the implementation. They're stored as free text and propagate through the agent context depth.

Both serve different purposes:

• Decisions answer "What did you choose and why?" -- useful for reviewing constraints.
• Execution records answer "What did you build and how?" -- useful for implementing dependent work.

Record both when completing a task. They're complementary, not redundant.