Skip to content

docs: add a concrete agent-failure example to make the harness claim tangible #91

@constk

Description

@constk

Problem

CLAUDE.md and the harness docs assert that the gates catch agent mistakes, but never show one. The claim "harness IS the product" reads abstract without a worked example. New readers (human or agent) have to take the promise on faith.

Proposed solution

Add a 3–5 line sidebar / callout to either CLAUDE.md or README.md with a concrete, real-feeling example. Suggested wording:

Example: an agent added a reverse import (tools → models). The lint-imports gate failed CI and pointed the agent at docs/BOUNDARIES.md. The mistake never shipped.

If a real captured incident exists (PR/CI run), link it instead of the synthetic example.

Acceptance criteria

  • One concrete example documented in CLAUDE.md or README.md
  • Example names a specific gate and the doc it routes the agent to
  • Stays under ~5 lines to avoid bloating either file

Priority rationale

Cheapest way to convert an abstract claim into something a reader can picture. Pairs naturally with the README opener reframe.

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-harnessClaude Code hooks, skills, settingsdocumentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions