Skip to content

feat: make human-facing output concise - #213

Merged
BjRo merged 2 commits into
mainfrom
docs/206-plain-language
Sep 19, 2026
Merged

BjRo merged 2 commits into
mainfrom
docs/206-plain-language

Conversation

@BjRo

@BjRo BjRo commented Sep 19, 2026

Copy link
Copy Markdown
Owner

Why

Closes #206. Darrow had no repository-wide plain-language contract, and several human-facing skill results buried the outcome or next action behind detail and process narration.

What changed

  • Add result-first writing rules to repository guidance, the documentation quality contract, user guides, and six capability specifications.
  • Revise discovery, explanation, readiness, review, verification, and skill-authoring output contracts for familiar language, progressive disclosure, and preserved evidence and safety fields.
  • Move review and readiness next actions ahead of detail, tighten verification handoffs, add semantic communication evals, and bump both manifests for every changed plugin.
  • Repair the discovery eval loophole test so semantic assertions remain semantic and give its shell loop a stable timeout under full-suite load.

Verification

  • PASS: bun run lint; bun run lint:ts; bun run lint:shell; bun run typecheck.
  • PASS: bun run check:decisions; bun run check:docs; bun run check:python; bun run check:python:inventory.
  • PASS: bun test — 632 tests, 0 failures.
  • PASS: all eight changed skills pass the bundled inspector.
  • PASS: the eight focused eval definitions dry-prepare on Codex and Claude Code.
  • Live focused trials passed on Codex for authoring, discovery, grilling, planning, visual explanation, readiness, review, and verification during development. Claude Code passed authoring, discovery, grilling, planning, visual explanation, and readiness.

Review notes

The riskiest changes are the fixed report ordering in darrow-review, the readiness result template, and the verification retained-report handoff. Deterministic renderer, composition, Python, and repository suites pass.

Two cross-host limitations remain visible in retained eval evidence: the Claude code-review presentation case has a longstanding zero-pass history because the candidate substitutes an ad hoc review for the artifact workflow, and verification reruns showed provider/backend lookup variance plus a concision-grader disagreement. The branch adds no migration, security, licensing, or external-state behavior.

Checklist

  • I have read and followed CONTRIBUTING.md, including the contribution licensing terms.
  • I added or updated the applicable invariant before implementation, or this change does not affect a capability invariant.
  • I added or updated colocated evals, or this change does not affect skill behavior.
  • I confirmed that each changed plugin remains self-contained, or this change does not affect plugin content.
  • I ran bun run check:python, or this change does not affect registered Python packages or their repository quality infrastructure.

@BjRo
BjRo merged commit 9c36e51 into main Sep 19, 2026
80 checks passed
@BjRo
BjRo deleted the docs/206-plain-language branch September 19, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make Darrow documentation and generated output concise and clear

1 participant