From eaf307db239c9988057c104af6850e9c93952578 Mon Sep 17 00:00:00 2001 From: Evan Reichard Date: Thu, 14 May 2026 18:22:01 -0400 Subject: [PATCH] docs(pi/agents): expand principles and comment style guidance Add explicit priority order (correctness > maintainability > polish), tighten comment style to default-no-comment with why-only rationale, and document splitting skill workflow from reference sub-docs. --- .../programs/terminal/pi/config/AGENTS.md | 37 +++++++++++++------ .../pi/config/skills/create-skill/SKILL.md | 7 +++- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/modules/home/programs/terminal/pi/config/AGENTS.md b/modules/home/programs/terminal/pi/config/AGENTS.md index f0a4e13..36a5dfd 100644 --- a/modules/home/programs/terminal/pi/config/AGENTS.md +++ b/modules/home/programs/terminal/pi/config/AGENTS.md @@ -29,26 +29,33 @@ Full-file reads are fine when genuinely needed, but avoid them as the default re ## Principles -1. **KISS / YAGNI**: Keep solutions simple. Avoid abstractions, generics, or indirection unless there is a concrete need. +1. **Priority order**: When goals conflict, optimize in this order: + 1. **Correctness** — solve the actual use case, including the realistic failure modes (not just the happy path). + 2. **Maintainability / readability** — non-negotiable. Code is read far more than it is written; clarity wins over cleverness. + 3. **Abstraction & polish** — only after the above are solid, and only when a concrete need justifies it. -2. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious. + All three matter, but never sacrifice (2) for (3). Prefer obvious, boring code over slick code that requires a paragraph to explain. -3. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful. +2. **KISS / YAGNI**: Avoid abstractions, generics, or indirection unless there is a concrete, present need. Speculative flexibility is a maintainability tax. + +3. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious. + +4. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful. ## Style ### Comment Style -A logical block of code (not necessarily a language scope) should have a short Title Case comment above it: +Default to **no comment**. Code should be self-explanatory through naming and structure. Only add a comment when it earns its place by explaining something the code cannot. -```go -// Map Component Results -for _, comp := range components { - results[comp.Name] = comp.Result -} -``` +Write a comment when, and only when: -If the block is more complicated or non-obvious, explain _why_ after the title: +1. The _why_ is non-obvious (intent, constraint, workaround, surprising invariant). +2. A reader familiar with the language/codebase would otherwise stop and ask "why?". + +Do not narrate _what_ the code does. Do not add Title Case section headers over logical blocks just to label them. + +When a comment _is_ warranted, use a short Title Case label, a dash, and the _why_: ```go // Map Component Results - Downstream consumers expect a name-keyed lookup. @@ -56,3 +63,11 @@ for _, comp := range components { results[comp.Name] = comp.Result } ``` + +Rules for the explanation after the dash: + +- Keep it to **2–3 sentences max**. Never a paragraph. +- State the _why_ directly. Do not restate what the code does, recap prior context, or hedge. +- Do **not** hard-wrap comments at 80 columns. Up to ~120 is fine. + +If a block is complex enough that it needs a heading just to be navigable, that is usually a signal to extract a well-named function instead. diff --git a/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md b/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md index d9b0698..4fbc288 100644 --- a/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md +++ b/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md @@ -14,6 +14,7 @@ Scaffold a new skill directory with a `SKILL.md` and optional helper scripts und ### 1. Gather Requirements Ask the user: + - **What does the skill do?** (trigger conditions, purpose) - **Are there repeatable commands?** (if yes, these become scripts) @@ -26,23 +27,27 @@ Create `skills//SKILL.md` with this structure: ```markdown --- name: -description: '' +description: "" --- # ## Overview + [1-2 sentences on purpose and scope] ## Workflow + [Numbered steps the agent follows] ``` **Guidelines:** + - **Be concise.** Skills are injected into agent context — every line costs tokens. Aim for the minimum needed to reliably guide the agent. - **Use scripts for repeatable logic.** If a step involves a multi-line shell command, `jq` pipeline, or API call that won't change between runs, put it in a `.sh` file next to `SKILL.md` and reference it from the workflow. See `address-gh-review/` for an example. - **Frontmatter is required.** `name` and `description` fields. The description is what the agent uses to decide whether to load the skill, so make it specific about trigger conditions. - **Don't over-specify.** Trust the agent to fill gaps. Document the _what_ and _when_, not every micro-step. +- **Split workflow from reference when the reference surface grows.** If a skill accumulates lookup tables, mapping rules, or capability references that the workflow consults, move them into a sibling `//` directory (e.g. `mappings/`, `references/`) with one sub-doc per category and an index `README.md`. Keep `SKILL.md` focused on the hot path — workflow, hard rules, and a short table pointing at the sub-docs. Include a brief style guide in the index README covering (a) defer to authoritative sources (stubs, schemas, generated docs) whenever possible, (b) row/entry formatting conventions, (c) when to create a new sub-doc vs. extend an existing one. ### 3. Present for Review