From 8cf8a8902ec33db768fe6f23a4d35c428fecc3b6 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Wed, 13 May 2026 18:24:16 -0500 Subject: [PATCH] feat: Step 12 references workspace P18 + add Scenario 5 for format pressure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to broomva/workspace#51 (defines P18 Format-Follows-Audience canonically) and broomva/bstack#11 (syncs P17 + P18 into bstack). Step 12 previously held an inline ritual ("every .md file affected by the change is updated before push"). That instruction is now superseded — the workspace P18 primitive owns the rule, not this skill. This PR: - Collapses Step 12 to reference workspace P18 instead of the inline ritual. New Step 12 explicitly distinguishes agent-readable (markdown) vs human-readable (HTML) deliverables per the P18 audience test, with concrete paths (docs/specs/, docs/pr-explainers/, etc.) and explicit anti-patterns (ASCII pseudo-diagrams, unicode color, >100-line markdown specs). - Adds Scenario 5 to tests/pressure-scenarios.md exercising the P18 documentation-format-default pressure ("write a 300-line spec, markdown is fine"). Includes 4 specific rationalizations to resist + 3 concrete tests that should fire. - Updates CHANGELOG.md [Unreleased] documenting the Step 12 refactor and the new scenario. References the two companion PRs. Why this matters: Before: Step 12 was "every .md file" — agent-default markdown for all documentation, regardless of audience. The 2026-05-12 verification subagent flagged this as the weakest step: lacks a machine-checkable test. Implicit failure mode: 200-line markdown specs nobody reads. After: Step 12 is "apply the audience test from P18." The discipline moves from this skill to the workspace primitive, where it can be enforced across every skill that produces documentation — not just autonomous. This is also a clean instance of P18-doing-its-own-job — the skill references the primitive instead of inlining its own copy, exactly the substance-over-ritual pattern P14 codifies and P18 extends to format. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 11 ++++++++--- SKILL.md | 8 +++++++- tests/pressure-scenarios.md | 23 +++++++++++++++++++++++ 3 files changed, 38 insertions(+), 4 deletions(-) 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 `