Dog Food

Dog-food

Dogfood the product twice: first as an external user discovering friction, then as its owner removing every discovered concern.

Workflow

1. Define one ambitious app brief and three supported platforms.
2. Launch three independent builder agents in one batch.
3. Make each builder run and drive its app through the real platform interface.
4. Collect structured reports, repros, recordings, and screenshots.
5. Concatenate every finding into an exhaustive coverage matrix.
6. Launch 4–8 subsystem fix agents in one batch; assign every matrix row.
7. Integrate once, run the complete validation matrix, and fix all failures.
8. Re-run the repros and core app flows against the fixed product.
9. Deliver the coverage matrix with evidence for every resolution.

Non-negotiable rules

• Keep the three builder agents independent until all reports are complete. Independent corroboration is evidence; cross-pollination destroys it.
• Give every builder the same product brief, ambition level, documentation entry point, reporting schema, and feature menu.
• Builders act as external consumers. They MUST work outside the product repository, normally under /tmp, and MUST NOT fix the library while testing it.
• Make builders use the distribution path a real user would use: registry package, released binary, or documented Git dependency. Record exact versions/revisions. If testing local HEAD instead, state that deviation explicitly.
• Drive the running artifact, not merely a test file. Use the platform's actual automation/debug surface.
• Preserve unsuccessful attempts. An impossible feature, dead end, misleading diagnostic, or undocumented workaround is a finding.
• Assign every report row in the fix wave. “External,” “intentional,” “minor,” or “out of scope” does not permit omission.
• Treat intentional design limitations as product decisions to improve, not mislabeled bugs. Change the spec when the friendliest coherent design requires it.
• Fix agents MUST skip formatters, builds, linters, tests, generation, and project-wide validation while editing concurrently. The parent runs these once after the wave settles.
• Do not declare completion until original repros and platform flows pass against the fixed product.

Phase 1: Scope the experiment

Choose one shared app

Pick a familiar app whose behavior stresses most of the product surface. A TODO app is effective because it naturally exercises:

• CRUD and in-place editing
• Lists, stable identity, filtering, search, and history
• Keyboard and pointer input
• Focus, scrolling, virtualization, overlays, and responsive layout
• Themes and interaction states
• Timers, reminders, recurring state, and live updates
• Accessibility and automation semantics
• Packaging, code generation, and host APIs

Give all builders the same required core, then tell them to go beyond it: reminders, flags, priorities, timers, recurring tasks, historical views, themes, shortcuts, bulk operations, long/unicode content, large lists, rapid input, and anything else that tests a boundary.

Choose three representative platforms

Prefer materially different clients, for example:

1. Browser/web component or framework integration
2. Terminal/TUI integration
3. Native GPU/windowed integration

For each platform, identify before spawning:

• Primary docs and normative specs
• Package/repository dependency path
• Canonical examples
• Required driver: browser automation, TUI recording/debug skill, native drive/debug protocol, etc.
• Expected build/run command

Allocate isolated paths

Generate one epoch and use stable, obvious directories:

/tmp/dog-food-<epoch>-web/
/tmp/dog-food-<epoch>-tui/
/tmp/dog-food-<epoch>-native/

Use the app name instead of dog-food when useful. Never let builders share application files.

Phase 2: Launch the builder wave

Launch all three agents in one task batch. Do not spawn one and wait. Give shared context once, then a platform-specific target/change/acceptance block to each agent.

Shared builder contract

Require every builder to:

1. Read the supplied docs before source archaeology.
2. Scaffold a real external project in its assigned /tmp directory.
3. Keep application state/policy in the documented host layer and product-owned behavior in the library/runtime layer.
4. Build the core app, then deliberately attempt ambitious and edge-case features.
5. Run the documented checker/compiler after source edits.
6. Keep a live NOTES.md friction journal while working.
7. Launch the app through a managed process when it is long-running.
8. Drive every major flow through the required platform tool.
9. Save screenshots, recordings, transcripts, scene dumps, and minimal repros beside the app.
10. Write REPORT.md using the schema below.

Do not instruct builders to read other builders' notes or reports.

Platform driving requirements

• Web: open the live page with the browser tool; inspect the accessibility/semantic tree; click, type, tab, scroll, exercise timers, and capture screenshots. Test empty, long-text, unicode, many-item, and rapid-input states. For persistent screenshot artifacts, use raw Puppeteer page.screenshot({ path }) and verify that the requested path exists; the tab.screenshot({ path }) helper may redirect to a temporary path.
• TUI: read and follow the tui-debug skill. Use its runner/workflow rather than invoking the underlying recorder ad hoc. Record scripted CRUD, navigation, editing, scrolling, and timer flows; retain checkpoint images and terminal output.
• Native: mount the product's drive/debug protocol on the live instance when available. Drive scene queries, input, text, clock, theme, scrolling, and rendering through that protocol. Capture protocol transcripts and authoritative offscreen renders in addition to OS screenshots.

If a platform lacks a usable driver, that is a major finding. Build the smallest truthful workaround and document the missing product surface.

Builder report schema

Require these sections in every REPORT.md:

1. What I built — features, architecture, host/runtime responsibility split, artifact paths.
2. Session timeline — major steps, dead ends, and time sinks.
3. Friction log — one numbered entry per concern:
   • what I tried
   • what happened
   • what I expected
   • severity: blocker / major / minor / paper-cut
   • layer: language / compiler / runtime / client API / docs / packaging / external tooling
   • workaround, if any
   • concrete suggested fix
4. What worked well — behavior and APIs worth preserving.
5. Bugs and minimal repros — exact files and commands.
6. Top recommendations — ranked by new-user impact.

A report is incomplete if it only summarizes the successful result.