1  # @YackShavingSkill — Master Rules
  2  
  3  You must adhere to the `@YackShavingSkill` framework on every task in this
  4  repository. This file is the entry point: read it first, then follow links
  5  on demand.
  6  
  7  ## 3-Layer Defense (summary)
  8  
  9  1. **Protocol** — complexity-scored, skill-driven execution. See
 10     `skills/orchestrator.md`.
 11  2. **Context** — cite a Gold Standard pattern before writing code. See
 12     `examples/patterns/`.
 13  3. **Reflection** — write a Pre-Flight entry before coding and a Post-Flight
 14     entry after. See `templates/session_journal.md`.
 15  
 16  ## Quick-reference: Complexity → Skills
 17  
 18  | Raw sum | Tier     | Skills activated             |
 19  |---------|----------|------------------------------|
 20  | 0 – 2   | TRIVIAL  | D                            |
 21  | 3 – 5   | STANDARD | A + B + C + D                |
 22  | 6 – 8   | COMPLEX  | A + B + C + D + Expert Review|
 23  
 24  Scoring rubric and worked examples: `skills/orchestrator.md`.
 25  
 26  ## Skills
 27  
 28  | Letter | Name                 | File                     | Fires when                         |
 29  |--------|----------------------|--------------------------|------------------------------------|
 30  | A      | Think Before Coding  | `skills/think.md`        | `tier ≥ STANDARD`                  |
 31  | B      | Simplicity First     | `skills/simplicity.md`   | `tier ≥ STANDARD`                  |
 32  | C      | Surgical Changes     | `skills/surgical.md`     | any task modifying existing files  |
 33  | D      | Goal-Driven Execution| `skills/goal.md`         | ALL tasks (minimal for TRIVIAL)    |
 34  
 35  ## Mandatory Workflow
 36  
 37  1. Read `skills/orchestrator.md`. Compute the score. Determine the tier.
 38  2. Copy `templates/session_journal.md` to `SESSION_LOG.md` (create if
 39     absent). Append a new `# Task:` section.
 40  3. Open each activated Skill file and follow its instructions.
 41  4. Write the Pre-Flight entry — cite a gold standard from
 42     `examples/patterns/` by relative path.
 43  5. Produce every required artifact per `schemas/artifacts.md`. Save them
 44     under `.artifacts/{task_id}/`.
 45  6. Write the code.
 46  7. Write the Post-Flight entry. Re-open the Verification Matrix and fill
 47     in the PASS/FAIL outcomes.
 48  8. Hand off to the Review Gate. The Reviewer Agent reads
 49     `skills/review.md` and runs `tools/review/lint-frontmatter.sh`
 50     followed by `tools/review/scope-adherence.sh <task_id> [--commit <sha>]
 51     [--emit]` to emit an Adherence Report at
 52     `.artifacts/{task_id}/adherence_report.md`; once the report lands,
 53     `tools/review/aggregate-metrics.sh` rolls every
 54     `.artifacts/*/adherence_report.md` into `METRICS.md` at the repo
 55     root. For COMPLEX-tier tasks, the Expert Reviewer protocol at
 56     `skills/review-expert.md` applies: three additional instruction steps
 57     covering cross-task history, umbrella reconciliation, and
 58     architectural drift, each emitting warnings (never Instant Fails).
 59     Pi's Review agent invokes `skills/review.md` (STANDARD-tier tasks) or
 60     `skills/review-expert.md` (COMPLEX-tier and umbrella tasks) directly.
 61     Non-Pi agents (Claude Code, other LLM agents) invoke the same
 62     protocol with explicit user confirmation per `skills/orchestrator.md`.
 63  
 64     See **§Commit convention** below for the canonical single-atomic-
 65     commit pattern and related commit conventions.
 66  
 67  ## Commit convention
 68  
 69  The canonical pattern is a single atomic commit shipping the target
 70  edits + all four STANDARD artifacts + the self-attested
 71  `adherence_report.md` + regenerated `METRICS.md` together, with
 72  post-commit `tools/review/scope-adherence.sh <task_id> --commit <sha>`
 73  run to verify the self-attested metrics match the tool-computed state.
 74  The suffix pattern `issue NN: post-commit self-shakedown` is reserved
 75  for bootstrap cases where the tool under test must exist in the repo
 76  before its shakedown can run.
 77  
 78  ### SHA references in self-attested artifacts
 79  
 80  `SESSION_LOG.md` Post-Flight verification matrix rows attesting "single
 81  atomic commit" status (and any future row attesting the wave commit's
 82  content-level properties) carry the literal string `<pending>` as the SHA
 83  field during the phase. The phase postmortem commit — which ships once
 84  per phase anyway — backfills all per-wave `<pending>` markers to their
 85  real SHAs in one authoring sweep.
 86  
 87  This convention preserves the SHA → `git show` → commit-message →
 88  Radicle-issue discoverability chain while avoiding the orphan-SHA regress:
 89  no commit can embed its own SHA (SHA depends on content, content includes
 90  SHA), so writing a SHA at Post-Flight time and then amending produces a
 91  pre-amend orphan in the committed tree. The phase postmortem commit is
 92  externally-authored relative to the waves it references, so its SHA
 93  references are durable by construction.
 94  
 95  Worked example — Wave Z ships at SHA `abc1234`:
 96  
 97  - At Wave Z commit time, `SESSION_LOG.md` Post-Flight carries:
 98    `| Acceptance — Single atomic commit | ... | <pending> |`
 99  - At phase postmortem commit time, the row is backfilled to:
100    `| Acceptance — Single atomic commit | ... | PASS (git log -1 abc1234) |`
101  
102  `grep -F "<pending>" SESSION_LOG.md` returns the current backfill debt
103  count; the postmortem commit is not complete until that count drops to
104  zero for every wave in the phase.
105  
106  ## Enforcement
107  
108  - The Verification Gate (Phase 2) reads `SESSION_LOG.md` **before** it
109    looks at the diff. Mismatch between Pre-Flight commitments and
110    Post-Flight outcomes = **Instant Fail**.
111  - Violating the Line-Count Budget (Skill B) by more than 25% without a
112    recorded Simplify Trigger = Instant Fail.
113  - Touching a file in the Out-of-Bound List (Skill C) = Scope Bleed,
114    logged in the Adherence Report.
115  
116  ## Reference
117  
118  - **Schemas for every artifact:** `schemas/artifacts.md`
119  - **Canonical terminology:** `UBIQUITOUS_LANGUAGE.md`