Hk Breadcrumb Creator

/hk-breadcrumb-creator — Workflow Breadcrumb Analysis

Traces a workflow through the harness-kit monorepo and produces a compact debugging reference. The output is for devs and agents who need to find where things break — not for onboarding docs or architecture overviews.

Context

<flow_context> $ARGUMENTS </flow_context>

If the context above is empty, ask: "Which flow do you want to trace? Describe it in terms of the user action or system event that kicks it off."

Step 0: Check existing breadcrumbs

Before scoping anything, read docs/breadcrumb_analysis/_INDEX.md to see what already exists. This file lists every breadcrumb folder and what it traces.

Compare the user's request against the existing entries and make one of three decisions:

1. Already covered — The flow is substantially documented in an existing breadcrumb. Tell the user which one covers it and what it contains. Ask if they want to update/extend that existing doc instead of creating a new one.

2. Partially overlapping — An existing breadcrumb covers part of the flow (e.g., user asks about "task execution" and spec-task-lifecycle/02-execute-and-dispatch/ covers the dispatch side but not the harness execution internals). Options:

   • Extend the existing breadcrumb (add sections to its FLOW/DETAILS/DEBUG files, or add a new sub-flow folder)
   • Create a new breadcrumb that covers the non-overlapping portion, cross-referencing the existing one

3. New territory — Nothing in the index covers this flow. Proceed to Step 1.

When extending an existing breadcrumb, read its current FLOW.md first so you don't duplicate content. Add new information that complements what's there — don't rewrite sections that are already accurate.

When creating a new breadcrumb that's adjacent to an existing one, add cross-references in both directions (a "See also" line in the new doc pointing to the existing one, and optionally a note in the existing doc pointing to the new one).

Present your decision to the user before proceeding. Something like:

Existing breadcrumbs I checked:
- spec-task-lifecycle/02-execute-and-dispatch — covers DAG dispatch, task status transitions
- harness-isolation-testing — covers harness CLI construction, MCP config, streaming

Your request overlaps with <X> in these areas: <list>.
I recommend: <extend existing / create new focused on Y / already covered>.

Step 1: Scope the flow

Before touching any code, define the boundaries:

FLOW: <name — short, kebab-case, used as folder name>
TRIGGER: <what kicks it off — button click, API call, CLI command, cron>
LAYERS: <which layers it touches — fe, api, celery, odin, db>
END STATE: <what the user/system sees when it completes>

If the flow is large (touches 5+ files per layer, or has multiple independent branches), break it into sub-flows. Each sub-flow gets its own folder. Create a parent _INDEX.md that links them.

Example of when to split:

• "spec execution" → split into: spec-planning, spec-task-dispatch, spec-task-execution, spec-assembly
• "task creation" → probably fine as one flow (FE form → API → DB → response)

Ask the user to confirm the scope before proceeding.

Step 2: Trace the flow

Work through each layer the flow touches, in execution order. For each hop, record:

1. Source file and function — where the action originates
2. What it does — one line, no fluff
3. What it passes — key data (payload shape, IDs, status values)
4. Where it goes next — the next file/function/service in the chain

Use the codebase directly. Read the actual code. Don't guess from file names.

Tracing tips

• Frontend → Backend: Search for the API URL in the frontend service files (src/services/). Match it to the Django URL conf and view.
• Backend → Celery: Search for .delay( or .apply_async( calls. Check config/celery.py and any tasks.py files.
• Backend → Odin: Look for subprocess calls to odin CLI or check dag_executor.py for execution strategy routing.
• Odin internals: Follow from cli.py → orchestrator.py → harness execute() methods.
• Signal/hook chains: Check Django signals, DRF perform_create/perform_update overrides, and model save() methods for side effects.

Step 3: Create the breadcrumb docs

Create the folder: docs/breadcrumb_analysis/<flow-name>/

Generate three files:

File 1: FLOW.md — High-level flow

This is the "where does data go" overview. Should be readable in 30 seconds.

Format:

# <Flow Name>

Trigger: <what starts it>
End state: <what the outcome is>

## Flow

<component/file> :: <function>
  → <what it sends / does>
<next component/file> :: <function>
  → <what it sends / does>
<next component/file> :: <function>
  → ...

## Sub-flows

(if applicable — link to sub-flow folders)

Example of the flow notation:

BoardView.tsx :: handleCreateTask()
  → POST /tasks/ {title, board_id, priority, status}
tasks/views.py :: TaskViewSet.create()
  → validates, saves to DB, returns TaskReadSerializer response
tasks/models.py :: Task.save()
  → triggers TaskHistory creation via signal

Keep it linear. If there's branching (e.g., different execution strategies), show each branch with a label:

tasks/dag_executor.py :: maybe_execute_task()
  → checks ODIN_EXECUTION_STRATEGY

  [strategy=local]
  dag_executor.py :: _execute_local()
    → subprocess: odin exec <task_id>

  [strategy=celery_dag]
  execution/celery_dag.py :: poll_and_execute()
    → picks up task on next poll cycle (every 5s)