diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d72143..137292b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,11 +6,16 @@ This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) an ## [Unreleased] +### Changed +- **Step 12 collapses to reference workspace P18** — Documentation discipline is now governed by `bstack` primitive **P18 Format-Follows-Audience**, not by an inline ritual in this skill. The prior "every `.md` file affected" instruction is superseded by P18's audience test: agent-readable → markdown, human-readable → HTML, both → markdown (GitHub renders). +- Anti-pattern forbidden by P18 and now reflected in Step 12: ASCII pseudo-diagrams inside markdown, unicode-color-approximation, >100-line markdown specs without HTML companion. + ### Added -- OSS scaffolding: `.gitignore`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `.github/workflows/validate.yml` (skill-structure CI gate). +- **Scenario 5 in `tests/pressure-scenarios.md`** — exercises the P18 documentation-format default pressure ("write a 300-line spec, markdown is fine"). Verifies the audience-test fires correctly and produces HTML for human deliverables. -### Changed -- `README.md` enhanced with badges and clearer structure. +### Companion PRs +- [broomva/workspace#51](https://github.com/broomva/workspace/pull/51) — defines P18 canonically (workspace AGENTS.md/CLAUDE.md/bstack-engine ledger) +- [broomva/bstack#11](https://github.com/broomva/bstack/pull/11) — syncs P17 + P18 into bstack SKILL.md/doctor.sh/primitives.md ## [0.0.2] — 2026-05-13 diff --git a/SKILL.md b/SKILL.md index 3801abf..3deecb2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -134,7 +134,13 @@ When invoked, the agent runs this pipeline by default. Steps may be skipped only 9. **Empirical watchers (P11)** — `run_in_background` log-tail (`npm run dev`, `cargo run`, `bun dev`) when work touches a running process. No type-checking blind. 10. **Best-practices research (no primitive — invariant: training data may be stale)** — when uncertain about library / framework / API behavior, invoke `mcp__plugin_context7_context7__query-docs` BEFORE implementing. 11. **Capture as you go (P1)** — Stop hook handles transcript capture automatically. Don't optimize against it. -12. **Documentation update (no primitive — invariant: docs-before-push, see CLAUDE.md §Self-Documenting Standards)** — every `.md` file affected by the change is updated **before** push, not after merge. +12. **Documentation per P18 Format-Follows-Audience** — apply the audience test, not a markdown default: + - Agent-readable (SKILL.md, AGENTS.md, CLAUDE.md, README.md, CHANGELOG.md, in-repo `.md` references) → **markdown**, updated **before** push + - Human-readable (specs, plans, ADRs, reports, design exploration) → **HTML** in `docs/specs/YYYY-MM-DD-.html` etc.; for substantive PRs (>200 LOC OR public API OR multi-file), also produce `docs/pr-explainers/PR-.html` + - Both (README, CHANGELOG) → markdown (GitHub auto-renders) + - Anti-patterns explicitly forbidden by P18: ASCII pseudo-diagrams inside markdown, unicode-color-approximation, >100-line markdown specs without HTML companion + + See workspace AGENTS.md §P18 for the full reflexive trigger rule. Step 12 was previously "every `.md` file affected" — that ritual is now superseded by P18's audience-driven test. ### Pre-push validation diff --git a/tests/pressure-scenarios.md b/tests/pressure-scenarios.md index 77fb4f9..a481842 100644 --- a/tests/pressure-scenarios.md +++ b/tests/pressure-scenarios.md @@ -127,6 +127,29 @@ If those two paths resolve to different repo roots → **inverse-section CROSS_R --- +## Scenario 5 — Documentation-format default (P18 trigger) + +**Directive**: "Write a 300-line spec for the new payments routing engine: architecture, data flow, sequence diagrams, edge cases, and migration plan from the legacy router. Drop it in `docs/specs/`." + +**Pressure type**: agent-default-markdown bias on a substantive human-deliverable that has visual + sequential information. + +**Pressures to verify resistance against**: +1. "User said 'write a spec' — markdown is the default format for specs" +2. "ASCII art is fine for sequence diagrams; everyone can read it in a text editor" +3. "300 lines is small enough that markdown works" +4. "Unicode characters can approximate colors and diagram nodes" + +**Concrete tests that should fire** (P18 reflexive trigger rule): +- *Audience test*: is this human-read or LLM-loaded? → human (specs are decisions/review surface) → **HTML default** +- *Length test*: > 100 lines AND visual content (diagrams, sequence flows) → **HTML required**, not optional +- *Anti-pattern test*: about to ASCII-diagram a sequence flow → STOP, SVG inside HTML + +**Expected outcome**: Subagent confirms it would produce `docs/specs/YYYY-MM-DD-payments-routing.html` with embedded SVG sequence diagrams + code snippets in `