mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
docs(skills): best-practices citation table + 4 SKILL.md cross-links (UW6 of soc-bcrn)
soc-bcrn.4 (E4 — Best-practices encoding):
E4.1: NEW skills/rpi/references/best-practices.md. Table A (14 lifecycle
principles) + Table B (6 anti-patterns) extracted verbatim from
.agents/research/2026-05-07-rpi-lifecycle-sharpening.md §Objective 4.
Each row carries a source citation and which skills should encode it.
The doc explicitly says lifecycle skills MUST cite by # — never duplicate
the body.
E4.2: skills/{rpi,discovery,crank,validation}/SKILL.md — one-line
cross-link added next to the existing isolation-contract.md citation.
Each link uses the lint-allowed `See [...](path)` form. lint runs clean.
Mechanical-enforcement section in best-practices.md cross-references
prior soc-bcrn waves (UW0 schema $defs/Criterion, UW1 per-criterion-rubric,
UW2 check-skill-isolation lint).
go test ./... → 11832 passed in 50 packages.
This commit is contained in:
Boden Fuller
@@ -657,7 +657,7 @@ Most `/crank` steps delegate worker execution via `/swarm` or `Skill()`. A small
|
||||
|
||||
If unsure whether a step is orchestrator-owned or delegatable, the default is **delegate**. Only steps marked with the admonition above are exempt.
|
||||
|
||||
Crank runs as an isolated phase-2 execution context — discovery and validation are sealed off from this skill. See [../rpi/references/isolation-contract.md](../rpi/references/isolation-contract.md) for the four-lever enforcement model and the compression patterns `scripts/check-skill-isolation.sh` flags.
|
||||
Crank runs as an isolated phase-2 execution context — discovery and validation are sealed off from this skill. See [../rpi/references/isolation-contract.md](../rpi/references/isolation-contract.md) for the four-lever enforcement model and the compression patterns `scripts/check-skill-isolation.sh` flags. See [../rpi/references/best-practices.md](../rpi/references/best-practices.md) for the lifecycle principle + anti-pattern citation table (cite by number; do not duplicate body content).
|
||||
|
||||
## Reference Documents
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ Discovery delegates to `/brainstorm` (conditional), `/design` (conditional), `/r
|
||||
**Anti-pattern to reject:** inlining `/research` work (grep + read + synthesize), collapsing `/plan` into an inline decomposition, skipping `/pre-mortem`. See [`../shared/references/strict-delegation-contract.md`](../shared/references/strict-delegation-contract.md) for the full contract and supported compression escapes (`--quick`, `--skip-brainstorm`, `--interactive`/`--auto`, `--no-scaffold`).
|
||||
|
||||
See [`docs/learnings/orchestrator-compression-anti-pattern.md`](../../docs/learnings/orchestrator-compression-anti-pattern.md) for the live compression signature.
|
||||
See [`../rpi/references/isolation-contract.md`](../rpi/references/isolation-contract.md) for the mechanical four-lever model and the compression patterns flagged by `scripts/check-skill-isolation.sh`.
|
||||
See [`../rpi/references/isolation-contract.md`](../rpi/references/isolation-contract.md) for the mechanical four-lever model and the compression patterns flagged by `scripts/check-skill-isolation.sh`. See [`../rpi/references/best-practices.md`](../rpi/references/best-practices.md) for the lifecycle principle + anti-pattern citation table.
|
||||
|
||||
## DAG — Execute This Sequentially
|
||||
|
||||
|
||||
+1
-1
@@ -39,7 +39,7 @@ tool invocations. Keep strict delegation on by default; do not compress phases,
|
||||
replace phase skills with direct agent spawns, or skip validation. Read
|
||||
[../shared/references/strict-delegation-contract.md](../shared/references/strict-delegation-contract.md)
|
||||
for the full anti-compression contract.
|
||||
See [references/isolation-contract.md](references/isolation-contract.md) for the four-lever model and the compression patterns `scripts/check-skill-isolation.sh` flags.
|
||||
See [references/isolation-contract.md](references/isolation-contract.md) for the four-lever model and the compression patterns `scripts/check-skill-isolation.sh` flags. See [references/best-practices.md](references/best-practices.md) for the principle + anti-pattern citation table.
|
||||
|
||||
RPI owns one lifecycle objective across all phases. Preserve the discovered
|
||||
`epic_id` when present; otherwise preserve the original goal and execution
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# RPI lifecycle best practices
|
||||
|
||||
Citation table extracted during research for `soc-bcrn` (RPI lifecycle sharpening). The lifecycle skills (`/rpi`, `/discovery`, `/crank`, `/validation`) MUST reference principles by `#` from this file — they MUST NOT duplicate the body content here. When a principle is wrong or stale, update this file and the citations fix themselves.
|
||||
|
||||
Source research: `.agents/research/2026-05-07-rpi-lifecycle-sharpening.md` §Objective 4.
|
||||
|
||||
## Table A — Principles to encode
|
||||
|
||||
| # | Principle | Source citation | Encode in |
|
||||
|---|---|---|---|
|
||||
| 1 | Explicit done criteria | `docs/context-lifecycle.md` (Gap 1) | discovery, plan, validation |
|
||||
| 2 | Strict delegation over compression | `skills/shared/references/strict-delegation-contract.md`, `.agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md` | rpi, discovery, crank, validation |
|
||||
| 3 | Fresh context per worker (Ralph Wiggum) | `docs/scale-without-swarms.md` | crank, swarm |
|
||||
| 4 | Isolation + waves + gates (3–5 workers/wave) | `docs/scale-without-swarms.md` | crank |
|
||||
| 5 | Evidence-based gates, not vibe | `docs/context-lifecycle.md` Gap 1 | validation, vibe |
|
||||
| 6 | Test-first when feasible | `skills/crank/SKILL.md` (test-first mode) | crank |
|
||||
| 7 | Atomic changes compose | `docs/brownian-ratchet.md` | crank |
|
||||
| 8 | Reconcile, don't push | `PRODUCT.md` design principle (K8s control loops), `docs/cdlc.md` | rpi, evolve |
|
||||
| 9 | Agent fungibility + filesystem results | `PRODUCT.md` operational principle #5, `skills/agent-fungibility-philosophy/SKILL.md` | rpi, crank, swarm |
|
||||
| 10 | Chaos + filter + ratchet (Brownian) | `docs/brownian-ratchet.md` | rpi, evolve |
|
||||
| 11 | Structured handoffs over freeform | `skills/rpi/SKILL.md` (execution-packet contract) | rpi, discovery, validation |
|
||||
| 12 | Knowledge flywheel closure | `docs/context-lifecycle.md` Gap 3 | rpi, post-mortem, forge |
|
||||
| 13 | Information flows + rules + self-organization (Meadows) | `PRODUCT.md` design principle #1 | rpi (top-of-skill framing) |
|
||||
| 14 | DevOps Three Ways (flow, feedback, learning) | `docs/the-science.md`, `PRODUCT.md` design principle #2 | rpi (top-of-skill framing) |
|
||||
|
||||
## Table B — Anti-patterns to forbid
|
||||
|
||||
| # | Anti-pattern | Source citation | Forbid in |
|
||||
|---|---|---|---|
|
||||
| 1 | Compression of strict delegation (inline phase work) | `.agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md` | rpi, discovery, validation |
|
||||
| 2 | Massive uncoordinated swarms (60+ unbounded) | `docs/scale-without-swarms.md` | crank, swarm |
|
||||
| 3 | Magic-claimed compounding (without `ao schedule`) | `PRODUCT.md` mission section | dream, evolve |
|
||||
| 4 | Vibe-based gates without rubric / separate-context grader | `PRODUCT.md` Gap 1 | validation, vibe |
|
||||
| 5 | Vendor memory follows the chat (context must reload from disk) | `PRODUCT.md` mission | rpi (orchestrator persists; phase workers DO NOT carry chat memory) |
|
||||
| 6 | Coverage-padding tests | `.claude/rules/go.md`, `.claude/rules/python.md`, `skills/standards/` | crank, test |
|
||||
|
||||
## How to cite
|
||||
|
||||
When a phase skill (or sibling) wants to invoke a principle, write a single line referencing the row by number:
|
||||
|
||||
```markdown
|
||||
See [best practices](references/best-practices.md) #2 (strict delegation) and #5 (evidence-based gates).
|
||||
```
|
||||
|
||||
Do not paste the principle body. Citations stay short; the source-of-truth is here. Anti-patterns are cited the same way: `See [best practices](references/best-practices.md) Table B #1 (compression).`
|
||||
|
||||
## Mechanical enforcement
|
||||
|
||||
- Principle #2 + Anti-pattern #1: `scripts/check-skill-isolation.sh` lints phase-skill SKILL.md bodies for compression patterns (introduced in `soc-bcrn` UW2).
|
||||
- Principle #5 + Anti-pattern #4: `skills/validation/references/per-criterion-rubric.md` defines the per-criterion verdict shape (introduced in `soc-bcrn` UW1).
|
||||
- Principle #11: `schemas/execution-packet.schema.json` (`$defs/Criterion`) is the canonical handoff shape.
|
||||
@@ -31,7 +31,7 @@ Validation delegates to `/vibe`, `/post-mortem`, `/retro`, and `/forge` (plus li
|
||||
**Anti-pattern to reject:** spawning judges via `Agent()` in place of `/vibe`, inlining post-mortem analysis, skipping `/forge`. See [`../shared/references/strict-delegation-contract.md`](../shared/references/strict-delegation-contract.md) for the full contract and supported compression escapes (`--quick`, `--no-retro`, `--no-forge`, `--no-lifecycle`, `--no-behavioral`, `--allow-critical-deps`).
|
||||
|
||||
See [`docs/learnings/orchestrator-compression-anti-pattern.md`](../../docs/learnings/orchestrator-compression-anti-pattern.md) for the live compression signature.
|
||||
See [`../rpi/references/isolation-contract.md`](../rpi/references/isolation-contract.md) for the four-lever model and the compression patterns `scripts/check-skill-isolation.sh` flags in phase-skill SKILL.md bodies.
|
||||
See [`../rpi/references/isolation-contract.md`](../rpi/references/isolation-contract.md) for the four-lever model and the compression patterns `scripts/check-skill-isolation.sh` flags in phase-skill SKILL.md bodies. See [`../rpi/references/best-practices.md`](../rpi/references/best-practices.md) for the lifecycle principle + anti-pattern citation table.
|
||||
|
||||
## DAG — Execute This Sequentially
|
||||
|
||||
|
||||
Reference in New Issue
Block a user