1  # YackShavingSkill — Ubiquitous Language & Vocabulary
  2  
  3  > **Purpose:** This document defines the canonical terms, concepts, and relationships used throughout the `@YackShavingSkill` project. All code, documentation, task specs, and conversations should use these terms consistently to eliminate ambiguity and ensure shared understanding.
  4  
  5  ---
  6  
  7  ## Table of Contents
  8  
  9  1. [Core Domain Concepts](#1-core-domain-concepts)
 10  2. [Skill Modules](#2-skill-modules)
 11  3. [Orchestration & Complexity](#3-orchestration--complexity)
 12  4. [Reflection Artifacts](#4-reflection-artifacts)
 13  5. [Verification & Review](#5-verification--review)
 14  6. [Repository Structure Terms](#6-repository-structure-terms)
 15  7. [Relationships & Glossary](#7-relationships--glossary)
 16  
 17  ---
 18  
 19  ## 1. Core Domain Concepts
 20  
 21  | Term | Definition | Usage Notes |
 22  |------|-----------|-------------|
 23  | **YackShavingSkill** | The overarching skill framework that operationalizes Karpathy-inspired coding principles into an active, agent-aware system. Referred to as `@YackShavingSkill` when referencing the project or installation. | "Install `@YackShavingSkill` into your Pi project." |
 24  | **Induced Complexity** | The tendency of LLM coding agents to over-engineer solutions, add unnecessary abstractions, or expand scope beyond the original request. Also called "feature bloat" or "complexity creep." | The phenomenon the framework is designed to counteract. |
 25  | **Agent Counterweight** | The conceptual role of `@YackShavingSkill` — providing architectural guardrails that actively restrain LLM tendencies toward over-engineering. | "The skill acts as an agent counterweight." |
 26  | **Artifact** | A concrete, structured output produced by a skill. Artifacts are tangible documents (checklists, reports, matrices, journal entries) rather than abstract guidance. | Skills produce artifacts; review gates consumes artifacts. |
 27  | **Gold Standard** | The ideal code patterns stored in the `examples/patterns/` directory. Concrete code examples that agents must reference and mimic to maintain project style consistency. | "The agent reads the Gold Standard before implementing." |
 28  | **Anti-Pattern** | Code examples stored in `examples/anti-patterns/` that demonstrate what to avoid. Used as negative references for the agent's self-review. | Contrasted with Gold Standard patterns. |
 29  
 30  ---
 31  
 32  ## 2. Skill Modules
 33  
 34  Four composable skill modules derive from the Karpathy principles. Each is a standalone unit that produces a specific artifact.
 35  
 36  ### 2.1 Skill A — `Think Before Coding`
 37  
 38  | Term | Definition |
 39  |------|-----------|
 40  | **Pre-Computation Block** | The artifact produced by this skill — a structured document containing assumptions, interpretations, alternatives, and scope declarations. |
 41  | **Assumptions List** | A list of all assumptions the agent is making about the request, each rated with a confidence level. |
 42  | **Confidence Score** | A qualitative rating (`HIGH`, `MEDIUM`, `LOW`) assigned to each assumption, indicating how certain the agent is of its validity. |
 43  | **Scope Declaration** | A statement within the pre-computation block explicitly listing which files/patterns will and will not be changed. |
 44  | **Alternatives Considered** | A record of simpler or different approaches that were evaluated and rejected, with rationale for each rejection. |
 45  
 46  ### 2.2 Skill B — `Simplicity First`
 47  
 48  | Term | Definition |
 49  |------|-----------|
 50  | **Simplicity Review** | The artifact produced by this skill — a self-assessment answering whether the simplest viable solution was chosen. |
 51  | **Line-Count Budget** | The estimated and actual number of lines of code for an implementation, compared to expose over-engineering. |
 52  | **Simplify Trigger** | A condition detected during the simplicity review that indicates the current approach is more complex than necessary, requiring revision. |
 53  | **Abstinence List** | What the agent explicitly chose NOT to implement — features, abstractions, or flexibility that were out of scope. |
 54  | **Intentional Exclusions** | Edge cases or error scenarios the agent is deliberately NOT handling in this task. |
 55  
 56  ### 2.3 Skill C — `Surgical Changes`
 57  
 58  | Term | Definition |
 59  |------|-----------|
 60  | **Change Boundary** | The artifact produced by this skill — a document specifying exactly which files will be modified and why, and which files will not be touched. |
 61  | **File Touch List** | The list of files the agent plans to modify, with a per-file rationale. |
 62  | **Out-of-Bound List** | The list of files explicitly declared as off-limits for this task. |
 63  | **Orthogonal Issues** | Improvements or bugs noticed by the agent that are unrelated to the task scope. These are flagged but deliberately not addressed. |
 64  | **Orphan Tracking** | The process of identifying imports, variables, or references that become unused as a direct result of this change. |
 65  | **Scope Bleed** | A violation where changes touch files or areas declared out-of-bound in the change boundary. |
 66  
 67  ### 2.4 Skill D — `Goal-Driven Execution`
 68  
 69  | Term | Definition |
 70  |------|-----------|
 71  | **Verification Matrix** | The artifact produced by this skill — a structured table mapping each subtask to explicit pass/fail criteria and test cases. |
 72  | **Subtask** | A discrete, testable unit of work within the larger task, each with its own verification criteria. |
 73  | **Pass/Fail Criteria** | Specific, testable conditions that determine whether a subtask is successfully completed. |
 74  | **Self-Loop** | An iteration where the agent attempts to fix a failed verification criterion without external intervention. |
 75  | **Escalation Trigger** | The condition (e.g., max self-loops reached, ambiguous failure) that causes the agent to stop and ask the user for guidance. |
 76  
 77  ---
 78  
 79  ## 3. Orchestration & Complexity
 80  
 81  ### 3.1 Complexity Orchestrator
 82  
 83  | Term | Definition |
 84  |------|-----------|
 85  | **Complexity Orchestrator** | The decision layer that calculates a task's complexity score (1–10) and activates the appropriate skill subset. |
 86  | **Complexity Score** | A numeric value from 1 to 10, calculated by summing four dimension scores. Determines which skills to activate. |
 87  | **Scope Size** | Complexity dimension: 1 point per file touched, maximum 5 points. |
 88  | **Ambiguity** | Complexity dimension: `LOW (0)`, `MEDIUM (1)`, `HIGH (2)`. Measures clarity of the request. |
 89  | **Risk Surface** | Complexity dimension: `INTERNAL (0)`, `PUBLIC-API (1)`, `CRITICAL-PATH (2)`. Measures impact of potential errors. |
 90  | **Knowledge Gap** | Complexity dimension: `NONE (0)`, `PARTIAL (1)`, `UNKNOWN (2)`. Measures how familiar the agent is with the relevant codebase area. |
 91  | **Skill Set Activation** | The mapping of complexity score to which skills are enabled (see severity tiers below). |
 92  
 93  ### 3.2 Severity Tiers
 94  
 95  | Tier | Score Range | Active Skills | Additional Requirements |
 96  |------|-------------|---------------|------------------------|
 97  | **TRIVIAL** | 1–3 | Goal-Driven only | Minimal verification matrix. |
 98  | **SIMPLE** | 4–7 | Goal-Driven + Simplicity First | Session Journal required. Gold Standard reference required. |
 99  | **STANDARD** | 4–7 | Goal-Driven + Simplicity First + Think Before Coding + Surgical Changes | Session Journal required. All skills active. |
100  | **COMPLEX** | 8–10 | ALL skills + Explicit user confirmation | Session Journal required. Expert Reviewer Agent required. |
101  
102  > **Note:** PRD v1 uses SIMPLE (3–5) and MEDIUM (6–8). PRD v2 uses STANDARD (4–7) and COMPLEX (8–10). The canonical mapping above reconciles both.
103  
104  ### 3.3 Adaptive Skill Injection
105  
106  | Term | Definition |
107  |------|-----------|
108  | **Adaptive Skill Injection** | The process by which the Complexity Orchestrator injects only the required skill templates into the execution plan, based on the calculated complexity score. |
109  | **Skill Wrapper** | A Pi task spec that wraps a skill's prompt template, allowing it to execute as a first-class Pi task. |
110  | **Plan Agent** | The agent responsible for complexity scoring, skill selection, and task generation during the Plan phase. |
111  | **Worker Agent** | The agent responsible for executing the work during the Work phase, guided by skill artifacts. |
112  | **Reviewer Agent** | The agent responsible for validating adherence to principles during the Review phase. Also called the "Expert Reviewer" at COMPLEX complexity. |
113  
114  ### 3.4 Agent Roles
115  
116  | Term | Definition |
117  |------|-----------|
118  | **Executor** | Synonym for Worker Agent. The agent that writes code. |
119  | **Reviewer** | Synonym for Reviewer Agent. The agent that checks code for principle adherence without writing code. |
120  | **Escalation Agent** | A third agent engaged only at COMPLEX complexity when the Reviewer detects violations exceeding a threshold. |
121  
122  ---
123  
124  ## 4. Reflection Artifacts
125  
126  The Reflection layer, introduced in PRD v2, adds a Session Journal as the primary reflection mechanism.
127  
128  ### 4.1 Session Journal
129  
130  | Term | Definition |
131  |------|-----------|
132  | **Session Journal** | A structured log file (`SESSION_LOG.md`) where the agent records its thinking before and after coding in two entries: Pre-Flight and Post-Flight. |
133  | **Journal Entry** | A single recorded block within the Session Journal. Each task produces at minimum two entries. |
134  | **Pre-Flight Entry** | Journal Entry #1 — written BEFORE coding. Captures the Simplicity Strategy, Scope Boundaries, Contextual References, and Assumptions. |
135  | **Post-Flight Entry** | Journal Entry #2 — written AFTER coding. Captures the Reflex Audit (Pass/Fail), Violation checks, and Verification Results. |
136  
137  ### 4.2 Pre-Flight Entry Structure
138  
139  | Field | Definition |
140  |-------|-----------|
141  | **Reflex Check** | A pair of commitments: (1) a Simplicity Goal stating the technique to use and the approach to avoid, and (2) explicit Scope Boundaries declaring In-Scope and Out-of-Scope items. |
142  | **Simplicity Strategy** | The agent's stated approach for keeping the solution minimal. Values: `MINIMAL`, `STANDARD`, `DEEP`. |
143  | **Contextual Retrieval** | A reference to which `examples/patterns/` file the agent is reading as its Gold Standard before implementation. |
144  | **Trade-off Record** | A documented comparison between two approaches with the rationale for the chosen approach. |
145  
146  ### 4.3 Post-Flight Entry Structure
147  
148  | Field | Definition |
149  |-------|-----------|
150  | **Reflex Audit** | A Pass/Fail judgment on whether the agent's final code met its Pre-Flight Simplicity Goal. Values: `PASSED`, `FAILED`. |
151  | **Violation Checklist** | Specific checks the agent performs on itself: Complexity Creep, Scope Bleed, Style Drift. Each checked as pass/fail. |
152  | **Style Drift** | A violation where the agent's code does not match the structure or patterns from the referenced Gold Standard example. |
153  | **Complexity Creep** | A violation where the agent added unused flags, hidden logic branches, or unnecessary abstractions beyond the Pre-Flight commitment. |
154  
155  ---
156  
157  ## 5. Verification & Review
158  
159  ### 5.1 Verification Gates
160  
161  | Term | Definition |
162  |------|-----------|
163  | **Verification Gate** | The post-hoc check that runs before changes are committed. Reads pre-computation and change-boundary artifacts, diffs actual changes against declared boundaries, and reports violations. |
164  | **Post-Hoc Verification** | Synonym for Verification Gate. Emphasizes that checking happens after execution, not before. |
165  | **Trust But Verify** | The operational philosophy: agents are allowed to proceed, but their output is mechanically checked against their own commitments. |
166  | **Violation** | Any deviation between what the agent declared it would do (in its artifacts) and what it actually did. |
167  | **Violation Count** | The number of detected violations. Used to determine whether to auto-accept, flag, or escalate. |
168  | **Violation Threshold** | The maximum violation count before requiring user intervention or escalation. |
169  
170  ### 5.2 Review Process
171  
172  | Term | Definition |
173  |------|-----------|
174  | **Principle Adherence** | The degree to which the agent's output follows the four core behavioral principles. This is the Reviewer Agent's sole concern. |
175  | **Adherence Report** | A summary emitted at task completion, reporting which skills fired, what artifacts were produced, and how many violations were detected. |
176  | **Diff Purity** | The percentage of changed lines that are directly attributable to stated goals (target: >95%). |
177  | **Orthogonal Change Rate** | The percentage of code changes to files or areas outside the declared scope (target: <5%). |
178  
179  ### 5.3 Review Phases
180  
181  | Term | Definition |
182  |------|-----------|
183  | **Pre-Flight** | The state before coding begins. The agent has produced its Journal Entry #1 and declared its boundaries. |
184  | **Post-Flight** | The state after coding ends, before review begins. The agent has produced its Journal Entry #2. |
185  | **Review Gate** | The entry point to the Review phase. The Reviewer Agent reads the Session Journal first, then inspects the code. |
186  | **Instant Fail** | When a Reviewer detects a direct contradiction between Pre-Flight commitments and Post-Flight output (e.g., committed to 20 lines, produced 200). The review fails immediately without deeper inspection. |
187  
188  ---
189  
190  ## 6. Repository Structure Terms
191  
192  ```
193  @YackShavingSkill/
194  ├── PRD.md                     # Product Requirements Document
195  ├── CLAUDE.md                  # Top-level master rules file (shorthand access)
196  ├── skills/                    # Modular skill prompt files
197  │   ├── think.md               # Skill A: Think Before Coding prompt
198  │   ├── simplicity.md          # Skill B: Simplicity First prompt
199  │   ├── surgical.md            # Skill C: Surgical Changes prompt
200  │   └── goal.md                # Skill D: Goal-Driven Execution prompt
201  ├── examples/                  # The Context Brain
202  │   ├── anti-patterns/         # Negative reference examples
203  │   │   ├── bloated-loop.md    # Example of unnecessary loop complexity
204  │   │   └── god-object.md      # Example of over-merged responsibilities
205  │   └── patterns/              # Positive reference examples (Gold Standard)
206  │       ├── simple-loop.md     # Example of clean, simple loops
207  │       └── surgical-diff.md   # Example of minimal, bounded changes
208  └── templates/                 # Reflection structures
209      └── session_journal.md     # The Session Journal template
210  ```
211  
212  | Term | Definition |
213  |------|-----------|
214  | **Master Rules** | The `CLAUDE.md` file — a concise, top-level reference of the four principles, providing quick access for agents. |
215  | **Skill File** | A single `.md` file in `skills/` containing the full prompt template for one skill module. |
216  | **Pattern File** | A file in `examples/patterns/` demonstrating a good code example for the agent to mimic. |
217  | **Anti-Pattern File** | A file in `examples/anti-patterns/` demonstrating a bad code example the agent must avoid. |
218  | **Journal Template** | The file in `templates/` providing the markdown structure for Session Journal entries. |
219  
220  ---
221  
222  ## 7. Relationships & Glossary
223  
224  ### 7.1 Entity Relationships
225  
226  ```
227  ┌──────────────────────────────────────────────────────────────────┐
228  │                     @YackShavingSkill                            │
229  │                                                                  │
230  │  PRD Phase      → Plan    → Work    → Review                     │
231  │                  (Orch.)   (Agent)   (Gate)                      │
232  │                                                                  │
233  │  Plan Agent calculates Complexity Score (1-10)                   │
234  │      │                                                         │
235  │      ├─→ TRIVIAL (1-3):  Goal-Driven only                      │
236  │      ├─→ SIMPLE/STANDARD (4-7): All 4 Skills + Journal          │
237  │      └─→ COMPLEX (8-10): All 4 Skills + Journal + Expert        │
238  │                                                                 │
239  │  Worker executes skills, produces Artifacts:                    │
240  │    - Think Before Coding  → Pre-Computation Block              │
241  │    - Simplicity First     → Simplicity Review                  │
242  │    - Surgical Changes     → Change Boundary                    │
243  │    - Goal-Driven          → Verification Matrix                │
244  │                                                                 │
245  │  Session Journal recorded by Worker:                            │
246  │    - Pre-Flight Entry (before coding)                           │
247  │    - Post-Flight Entry (after coding)                           │
248  │                                                                 │
249  │  Reviewer inspects:                                             │
250  │    1. Session Journal consistency                               │
251  │    2. Artifacts vs. actual code diff                            │
252  │    3. Gold Standard pattern compliance                          │
253  │    4. Generates Adherence Report                                │
254  └──────────────────────────────────────────────────────────────────┘
255  ```
256  
257  ### 7.2 Synonym Map
258  
259  | Preferred Term | Synonyms (use preferred in code/docs) |
260  |---------------|--------------------------------------|
261  | Complexity Orchestrator | Orchestrator |
262  | Session Journal | Journal |
263  | Pre-Flight / Post-Flight | Pre-Flight Entry / Post-Flight Entry |
264  | Verification Matrix | Verification |
265  | Verification Gate | Gate |
266  | Reflex Audit | Self-Audit |
267  | Gold Standard | Example Pattern |
268  | Anti-Pattern | Negative Example |
269  
270  ### 7.3 Abbreviations
271  
272  | Abbreviation | Full Term |
273  |-------------|-----------|
274  | PRD | Product Requirements Document |
275  | API | Application Programming Interface |
276  | CI/CD | Continuous Integration / Continuous Deployment |
277  
278  ### 7.4 Key Decisions & Conventions
279  
280  1. **Artifacts are primary.** Every skill MUST produce a concrete artifact. No skills without artifacts.
281  2. **Journal precedes code.** Pre-Flight Journal Entry is a gate — no file modifications until the agent has written it.
282  3. **Reviewer reads Journal first.** The review order is: Journal → Code. Inconsistencies between entries and code are violations.
283  4. **Violations are reported, not blocked.** By default, agents continue after producing a violation report, unless violations exceeded the threshold.
284  5. **Complexity drives activation.** Not all skills fire on all tasks. The Complexity Orchestrator determines activation.
285  6. **Examples beat descriptions.** When deciding style, agents reference `examples/patterns/` files over any textual description.
286  
287  ---
288  
289  *Created from PRD v1 (Agent Skill Framework) and PRD v2 (Context & Reflection Integrated). This document is the authoritative source for all terminology in the `@YackShavingSkill` project.*