Skip to content

docs: add LEARNING.md capturing harness design reflections #95

@constk

Description

@constk

Problem

The harness encodes a lot of opinions (mechanical gates, meta-gates, layered boundaries, agent hooks) but the why behind those choices isn't captured anywhere a reader can find quickly. New contributors and users have to reverse-engineer the rationale from the gates themselves.

Proposed solution

Add LEARNING.md at the repo root, ~200–300 words, covering:

  • What surprised the author while building the harness (where intuition was wrong).
  • Which gate has caught the most real mistakes, and what kind.
  • What would be done differently on a v2 (and why).

Keep it personal-voice and short — this isn't a design doc, it's a reflection.

Acceptance criteria

  • LEARNING.md exists at repo root, ~200–300 words
  • Covers: a surprise, a high-value gate, a thing-to-change
  • Linked from README.md (e.g. under "About this project" or similar)

Priority rationale

Polish — not a blocker for release. Adds a humanising dimension that the rest of the docs (intentionally terse) don't carry.

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