@vpxa/aikit 0.1.186 → 0.1.188

package/scaffold/dist/definitions/skills/adr-skill.mjs

@@ -1371,7 +1371,7 @@ function main() {
 main();
 `},{file:`SKILL.md`,content:`---
 name: adr-skill
-description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
+description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. Trigger on: architecture decisions, technology choices, significant design tradeoffs, decisions that affect >3 files or >1 team, irreversible choices. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
 metadata:
   category: cross-cutting
   domain: general
@@ -1400,23 +1400,26 @@ metadata:
 - **Simple** (≤3 options, single-team) — Context → Decision → Consequences → Implementation Plan → Alternatives
 - **MADR** (complex, multi-team) — Full template with Decision Drivers, Pros/Cons matrix, detailed Implementation Plan
 
-**Commands:**
-| Action | What to do |
-|--------|-----------|
-| Create | Run 4-phase workflow → save to \`docs/decisions/NNNN-slug.md\` |
-| Consult | \`search({ query: "ADR <topic>" })\` before implementing |
-| Update | Edit content, change status in YAML frontmatter |
-| Deprecate | Set \`status: deprecated\`, add superseded-by link |
-| Bootstrap | Create \`docs/decisions/\` + \`index.md\` if missing |
+**Commands:** Create → run 4-phase workflow and save to \`docs/decisions/NNNN-slug.md\`. Consult → \`search({ query: "ADR <topic>" })\` before implementing. Update → edit content and YAML status. Deprecate → set \`status: deprecated\` and add a superseded-by link. Bootstrap → create \`docs/decisions/\` plus \`index.md\` if missing.
 
 **Agent-readiness gate:** Every ADR scores ≥ 80% on: Specificity, Testability, Completeness, Independence, Actionability.
 
+## Mindset
+
+ADRs serve two audiences separated by time: the CURRENT team making the decision, and the FUTURE team wondering "why the hell did they do it this way?"
+
+The future audience is more important. They have zero context about your constraints, discussions, and tradeoffs. Write for them.
+
+An ADR is NOT meeting minutes. It captures:
+- The FORCES that drove the decision (constraints, requirements, team skills)
+- The ALTERNATIVES genuinely considered (with honest evaluation)
+- The IRREVERSIBILITY assessment (one-way door vs two-way door)
+- The CONSEQUENCES acknowledged upfront (technical debt accepted, capability traded)
+
 ## Philosophy
 
 ADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
 
-This means:
-
 - Constraints must be explicit and measurable, not vibes
 - Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
 - Consequences must map to concrete follow-up tasks
@@ -1424,6 +1427,16 @@ This means:
 - The ADR must be self-contained — no tribal knowledge assumptions
 - **The ADR must include an implementation plan** — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly
 
+## ADR Quality Criteria
+
+An ADR is agent-ready when it passes:
+- [ ] **Context is self-contained** — a reader unfamiliar with the project can understand the problem
+- [ ] **Options include at least 2 genuine alternatives** (no strawmen)
+- [ ] **Decision rationale cites concrete evidence** — performance numbers, blast radius, team constraints
+- [ ] **Consequences are bidirectional** — both benefits AND costs/risks
+- [ ] **Status is explicit** — proposed/accepted/deprecated/superseded with date
+- [ ] **Superseded ADRs link to their replacement** — no orphans
+
 ## When to Write an ADR
 
 Write an ADR when a decision:
@@ -1433,12 +1446,15 @@ Write an ADR when a decision:
 - **Affects other people or agents** who will work in this codebase later
 - **Has real alternatives** that were considered and rejected
 
-Do NOT write an ADR for:
+## NEVER
 
-- Routine implementation choices within an established pattern
-- Bug fixes or typo corrections
-- Decisions already captured in an existing ADR (update it instead)
-- Style preferences already covered by linters or formatters
+- **NEVER write an ADR after implementation** unless documenting a discovery — ADRs capture the decision moment, not post-hoc rationalization. If the code already exists, you're writing documentation, not a decision record.
+- **NEVER include only one option** — a "decision" with one choice isn't a decision. If there's genuinely only one approach, you don't need an ADR.
+- **NEVER use vague consequences** like "improves maintainability" — cite specific metrics, affected files, or observable outcomes.
+- **NEVER let ADRs accumulate without review** — stale "proposed" ADRs that languish >2 weeks should be accepted or withdrawn.
+- **NEVER modify an accepted ADR** — if the decision changes, SUPERSEDE with a new ADR that links back. History matters.
+- **NEVER write an ADR for trivial decisions** — library version bumps, formatting changes, and routine maintenance don't warrant the ceremony. Reserve ADRs for decisions that are hard to reverse or have team-wide impact.
+- **NEVER skip the "rejected alternatives" section** — documenting WHY you didn't pick option B is often more valuable than explaining why you picked A.
 
 When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.
 
@@ -1460,62 +1476,33 @@ Every ADR goes through four phases. Do not skip phases.
 
 ### Phase 0: Scan the Codebase
 
-Before asking any questions, gather context from the repo:
+Before asking questions, gather enough repo context to avoid contradictory ADRs:
 
-1. **Find existing ADRs.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\` for existing records. Read them. Note:
-
-   - Existing conventions (directory, naming, template style)
-   - Decisions that relate to or constrain the current one
-   - Any ADRs this new decision might supersede
-
-2. **Check the tech stack.** Read \`package.json\`, \`go.mod\`, \`requirements.txt\`, \`Cargo.toml\`, or equivalent. Note relevant dependencies and versions.
-
-3. **Find related code patterns.** If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
-
-4. **Check for ADR references in code.** Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
-
-5. **Note what you found.** Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
+1. **Find existing ADRs.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`. Note directory, naming, status style, related decisions, and anything this ADR might supersede.
+2. **Check the tech stack.** Read \`package.json\`, \`go.mod\`, \`requirements.txt\`, \`Cargo.toml\`, or equivalent for relevant dependencies and versions.
+3. **Find related code patterns.** Identify the files, directories, and implementation patterns this decision will affect.
+4. **Look for ADR references in code.** Comments and docs often reveal which decisions already govern an area.
 
 ### Phase 1: Capture Intent (Socratic)
 
-Interview the human to understand the decision space. Ask questions **one at a time**, building on previous answers. Do not dump a list of questions.
+Interview the human to understand the decision space. Ask questions **one at a time**, building on previous answers.
 
 **Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):
 
-1. **What are you deciding?** — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W").
-2. **Why now?** — What broke, what's changing, or what will break if you do nothing? This is the trigger.
-3. **What constraints exist?** — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 ("I see you're already using X — does that constrain this?").
-4. **What does success look like?** — Measurable outcomes. Push past "it works" to specifics (latency, throughput, DX, maintenance burden).
-5. **What options have you considered?** — At least two. For each: what's the core tradeoff? If they only have one option, help them articulate why alternatives were rejected.
-6. **What's your current lean?** — Capture gut intuition early. Often reveals unstated priorities.
-7. **Who needs to know or approve?** — Decision-makers, consulted experts, informed stakeholders.
-8. **What would an agent need to implement this?** — Which files/directories are affected? What existing patterns should it follow? What should it avoid? What tests would prove it's working? This directly feeds the Implementation Plan.
-
-**Adaptive follow-ups**: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:
-
-- "What's the worst-case outcome if this decision is wrong?"
-- "What would make you revisit this in 6 months?"
-- "Is there anything you're explicitly choosing NOT to do?"
-- "What prior art or existing patterns in the codebase does this relate to?"
-- "I found [existing ADR/pattern] — does this new decision interact with it?"
+1. **What are you deciding?** Push for a short verb phrase title ("Choose X", "Adopt Y", "Replace Z with W").
+2. **Why now?** What changed, broke, or will break if you do nothing?
+3. **What constraints exist?** Tech stack, timeline, budget, team skills, compliance, and existing decisions.
+4. **What does success look like?** Turn "it works" into measurable outcomes.
+5. **What options were considered?** At least two real alternatives, each with a core tradeoff.
+6. **What's the current lean?** Capture the instinct and the reason.
+7. **Who decides?** List decision-makers, consulted experts, and informed stakeholders.
+8. **What would an agent need to implement this?** Affected files, patterns to follow/avoid, config changes, and verification.
 
-**When to stop**: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.
+**Adaptive follow-ups**: probe where the decision is fuzzy. Useful prompts: "What's the worst-case outcome if this is wrong?", "What would make you revisit this in 6 months?", and "I found [existing ADR/pattern] — does this interact with it?"
 
-**Intent Summary Gate**: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:
+**When to stop**: stop only when every ADR section, especially Implementation Plan and Verification, can be filled without guessing.
 
-> **Here's what I'm capturing for the ADR:**
->
-> - **Title**: {title}
-> - **Trigger**: {why now}
-> - **Constraints**: {list}
-> - **Options**: {option 1} vs {option 2} [vs ...]
-> - **Lean**: {which option and why}
-> - **Non-goals**: {what's explicitly out of scope}
-> - **Related ADRs/code**: {what exists that this interacts with}
-> - **Affected files/areas**: {where in the codebase this lands}
-> - **Verification**: {how we'll know it's implemented correctly}
->
-> **Does this capture your intent? Anything to add or correct?**
+**Intent Summary Gate**: Before moving to Phase 2, summarize the title, trigger, constraints, options, current lean, non-goals, related ADRs/code, affected files, and verification plan, then ask: **Does this capture your intent? Anything to add or correct?**
 
 Do NOT proceed to Phase 2 until the human confirms the summary.
 
@@ -1535,7 +1522,7 @@ Do NOT proceed to Phase 2 until the human confirms the summary.
 
    - Use \`assets/templates/adr-simple.md\` for straightforward decisions (one clear winner, minimal tradeoffs).
    - Use \`assets/templates/adr-madr.md\` when you need to document multiple options with structured pros/cons/drivers.
-   - See \`references/template-variants.md\` for guidance.
+  - See \`references/template-variants.md\` if unsure.
 
 4. **Fill every section from the confirmed intent summary.** Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).
 
@@ -1549,7 +1536,7 @@ Do NOT proceed to Phase 2 until the human confirms the summary.
 
 ### Phase 3: Review Against Checklist
 
-After drafting, review the ADR against the agent-readiness checklist in \`references/review-checklist.md\`.
+After drafting, review the ADR against the inline quality criteria above, then use \`references/review-checklist.md\` for the full pass.
 
 **Present the review as a summary**, not a raw checklist dump. Format:
 
@@ -1564,70 +1551,29 @@ After drafting, review the ADR against the agent-readiness checklist in \`refere
 >
 > **Recommendation**: {Ship it / Fix the gaps first / Needs more Phase 1 work}
 
-Only surface failures and notable strengths — do not recite every passing checkbox.
-
-If there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.
-
-Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.
+Only surface failures and notable strengths. If there are gaps, propose specific fixes. Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.
 
 ## Consulting ADRs (Read Workflow)
 
 Agents should read existing ADRs **before implementing changes** in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.
 
-### When to Consult ADRs
-
-- Before starting work on a feature that touches architecture (auth, data layer, API design, infrastructure)
-- When you encounter a pattern in the code and wonder "why is it done this way?"
-- Before proposing a change that might contradict an existing decision
-- When a human says "check the ADRs" or "there's a decision about this"
-- When you find an ADR reference in a code comment
-
-### How to Consult ADRs
-
-1. **Find the ADR directory.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`. Also check for an index file (\`README.md\` or \`index.md\`).
+Consult ADRs:
 
-2. **Scan titles and statuses.** Read the index or list filenames. Focus on \`accepted\` ADRs — these are active decisions.
-
-3. **Read relevant ADRs fully.** Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.
-
-4. **Respect the decisions.** If an accepted ADR says "use PostgreSQL," don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.
-
-5. **Follow the Implementation Plan.** When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says "all new queries go through the data-access layer in \`src/db/\`," do that.
-
-6. **Reference ADRs in your work.** Add ADR references in code comments and PR descriptions (see "Code ↔ ADR Linking" below).
+1. **Before architecture work.** Especially auth, data layer, API design, infra, or any change that could contradict an existing decision.
+2. **Find the ADR directory and index.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`, then read \`README.md\` or \`index.md\` if present.
+3. **Focus on accepted ADRs first.** Those are the active rules unless superseded.
+4. **Read the full ADR, not just the title.** Context, decision, consequences, non-goals, and Implementation Plan all matter.
+5. **Follow the Implementation Plan.** If an ADR says new queries go through \`src/db/\`, do that.
+6. **Escalate conflicts.** If code and ADR disagree, or a new change would contradict an accepted ADR, flag it or draft a superseding ADR.
+7. **Reference the ADR in your work.** Link it in code comments or PR notes when the decision directly governs the change.
 
 ## Code ↔ ADR Linking
 
 ADRs should be bidirectionally linked to the code they govern.
 
-### ADR → Code (in the Implementation Plan)
-
-The Implementation Plan section names specific files, directories, and patterns:
-
-\`\`\`markdown
-## Implementation Plan
-
-- **Affected paths**: \`src/db/\`, \`src/config/database.ts\`, \`tests/integration/\`
-- **Pattern**: all database queries go through \`src/db/client.ts\`
-\`\`\`
-
-### Code → ADR (in comments)
-
-When implementing code guided by an ADR, add a comment referencing it:
-
-\`\`\`typescript
-// ADR: Using sql.js for test database
-// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
-import initSqlJs from 'sql.js';
-\`\`\`
-
-Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.
-
-### Why This Matters
-
-- An agent working in \`src/db/\` can find which ADRs govern that area
-- An agent reading an ADR can find the code that implements it
-- When an ADR is superseded, the code references make it easy to find all code that needs updating
+- **ADR → Code**: the Implementation Plan should name affected paths, patterns, config changes, and verification commands.
+- **Code → ADR**: add one lightweight comment at the entry point that links back to the governing ADR.
+- **Why**: this makes the reasoning discoverable in both directions and makes superseded decisions easier to unwind.
 
 ## Other Operations
 
@@ -1650,7 +1596,7 @@ After an ADR is accepted:
 2. **Reference the ADR in PRs.** Link to the ADR in PR descriptions, e.g. "Implements \`contributing/decisions/2025-06-15-use-sqlite-for-test-database.md\`."
 3. **Add code references.** Add ADR path comments at key implementation points.
 4. **Check verification criteria.** Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in \`## More Information\`.
-5. **Revisit when triggers fire.** If the ADR specified revisit conditions ("if X happens, reconsider"), monitor for those conditions.
+5. **Revisit when triggers fire.** If the ADR specified revisit conditions, monitor them.
 
 ### Index
 
@@ -1671,64 +1617,36 @@ node scripts/bootstrap_adr.js
 
 This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use \`--json\` for machine-readable output. Use \`--dir\` to override the directory name.
 
-### Categories (Large Projects)
-
-For repos with many ADRs, organize by subdirectory:
-
-\`\`\`
-docs/decisions/
-  backend/
-    2025-06-15-use-postgres.md
-  frontend/
-    2025-06-20-use-react.md
-  infrastructure/
-    2025-07-01-use-terraform.md
-\`\`\`
-
-Date prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.
-
 ## Resources
 
 ### scripts/
 
 - \`scripts/new_adr.js\` — create a new ADR file from a template, using repo conventions.
-- \`scripts/set_adr_status.js\` — update an ADR status in-place (YAML front matter or inline). Use \`--json\` for machine output.
-- \`scripts/bootstrap_adr.js\` — create ADR dir, \`README.md\`, and initial "Adopt ADRs" decision.
+- \`scripts/set_adr_status.js\` — update ADR status in-place. Use \`--json\` for machine output.
+- \`scripts/bootstrap_adr.js\` — create ADR dir, \`README.md\`, and an initial "Adopt ADRs" decision.
 
 ### references/
 
-- \`references/review-checklist.md\` — agent-readiness checklist for Phase 3 review.
+- \`references/review-checklist.md\` — full Phase 3 checklist.
 - \`references/adr-conventions.md\` — directory, filename, status, and lifecycle conventions.
-- \`references/template-variants.md\` — when to use simple vs MADR-style templates.
-- \`references/examples.md\` — filled-out short and long ADR examples with implementation plans.
+- \`references/template-variants.md\` — when to use simple vs MADR.
+- \`references/examples.md\` — filled-out examples.
 
 ### assets/
 
 - \`assets/templates/adr-simple.md\` — lean template for straightforward decisions.
-- \`assets/templates/adr-madr.md\` — MADR 4.0 template for decisions with multiple options and structured tradeoffs.
-- \`assets/templates/adr-readme.md\` — default ADR index scaffold used by \`scripts/bootstrap_adr.js\`.
+- \`assets/templates/adr-madr.md\` — MADR 4.0 template for structured tradeoffs.
+- \`assets/templates/adr-readme.md\` — default ADR index scaffold.
 
 ### Script Usage
 
-From the directory that contains this skill's \`scripts/\` folder:
-
 \`\`\`bash
-# Simple ADR
 node scripts/new_adr.js --title "Choose database" --status proposed
 
-# MADR-style with options
-node scripts/new_adr.js --title "Choose database" --template madr --status proposed
-
-# With index update
 node scripts/new_adr.js --title "Choose database" --status proposed --update-index
-
-# Bootstrap a new repo
+node scripts/new_adr.js --title "Choose database" --template madr --status proposed
 node scripts/bootstrap_adr.js --dir docs/decisions
 \`\`\`
 
-Notes:
-
-- Scripts auto-detect ADR directory and filename strategy.
-- Use \`--dir\` and \`--strategy\` to override.
-- Use \`--json\` to emit machine-readable output.
+Scripts auto-detect ADR directory and filename strategy. Use \`--dir\`, \`--strategy\`, and \`--json\` when you need overrides or machine-readable output.
 `}];export{e as default};