Skip to content

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

Closed

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.

Activity

  1. added
    documentationImprovements or additions to documentation
    claude-harnessClaude Code hooks, skills, settings
    on May 25, 2026
  2. constk commented on May 26, 2026

    @constk
    OwnerAuthor

    Closed via #100 (merged to develop as commit 7c84f18). Awaiting the next release: PR to reach main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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