Skip to content

docs: add DEMO.md walking through harness-catches-mistake in 60 seconds #96

@constk

Description

@constk

Problem

A new reader can grok what gates exist (HARNESS.md inventories them) but has no quick experiential path to feel them working. The "harness IS the product" claim is asserted, not demonstrated.

Proposed solution

Add DEMO.md at the repo root with a ~60-second walkthrough:

  1. Clone + bootstrap (link to DEVELOPMENT.md, don't duplicate).
  2. Add a deliberately bad change (e.g. a reverse import from tools to models, or an untyped public function).
  3. Run just check (or push a branch) and show the exact gate output that catches it.
  4. Fix the change, re-run, show green.

Keep prose minimal — code blocks and a short caption per step.

Acceptance criteria

  • DEMO.md exists at repo root
  • Walks through one concrete bad-change → gate-fail → fix → gate-pass cycle
  • Names the specific gate and links to the doc the gate routes a reader to
  • Linked from README.md near the harness pitch

Priority rationale

Polish — turns the harness story from an assertion into something a reader can run in a minute.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions