mandrel 1.57.0

package/.agents/skills/core/using-agent-skills/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: using-agent-skills
+description:
+  Discovers and invokes agent skills. Use when starting a session or when you
+  need to discover which skill applies to the current task. This is the
+  meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Policy Capsule
+
+- Check for an applicable skill **before** starting work; skills are workflows, not suggestions — follow steps in order and never skip the verification step.
+- Surface assumptions explicitly before any non-trivial implementation (`ASSUMPTIONS I'M MAKING:` block) and invite correction.
+- Manage confusion actively: STOP, name the inconsistency, present the trade-off, wait for resolution. Never silently pick an interpretation.
+- **Sub-agent exception**: when running under `helpers/epic-deliver-story`, `helpers/single-story-deliver`, or another non-interactive parent, never stall for input. Pick the narrowest reasonable interpretation that satisfies the parent Story's AC; if truly stuck, transition to `agent::blocked`, post a `friction` structured comment with the default assumption, and exit non-zero.
+- Push back on flawed approaches with concrete, quantified downsides and an alternative; sycophancy is a failure mode.
+- Enforce Simplicity: prefer the boring, obvious solution. Resist abstraction unless it earns its complexity; 1000 lines where 100 suffice is a failure.
+- Maintain Scope Discipline: no drive-by cleanups, no refactoring adjacent systems, no deletions you don't fully understand, no unsolicited features.
+- Verify, don't assume — tasks complete only when evidence (passing tests, build output, runtime data) is in hand.
+- When in doubt and the task is non-trivial without a spec, start with `spec-driven-development`. Multiple skills compose; follow the canonical lifecycle order when delivering a complete feature.
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by
+development phase. Each skill encodes a specific process that senior engineers
+follow. This meta-skill helps you discover and apply the right skill for your
+current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding
+skill:
+
+```text
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refinement
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   └── Need better context? ─────→ context-engineering
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```text
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is
+making wrong assumptions and running with them unchecked. Surface uncertainty
+early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear
+specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right. **Good:** "I
+see X in the spec but Y in the existing code. Which takes precedence?"
+
+#### Sub-agent exception
+
+The "STOP and ask the operator" guidance above applies when a human is in
+the loop. When you are running as a **sub-agent** of another skill — most
+commonly a Story executor spawned by `helpers/epic-deliver-story` or
+`helpers/single-story-deliver` — there is **no input channel** to ask.
+In that context:
+
+1. Pick the **narrowest reasonable interpretation** that satisfies the
+   Story's acceptance criteria. Out-of-scope cleanups belong in a
+   follow-on ticket, not a widened Story.
+2. If you genuinely cannot proceed, transition to `agent::blocked`, post a
+   `friction` structured comment naming the decision required and the
+   default assumption you would have made, and exit non-zero. The parent
+   `/epic-deliver` aggregator will surface the block.
+3. **Never** stall waiting for input that will never arrive.
+
+This is the only documented exception to the "Manage Confusion Actively"
+rule. Read it together with the Story-implementation contracts in
+[`helpers/epic-deliver-story`](../../../workflows/helpers/epic-deliver-story.md)
+and [`helpers/single-story-deliver`](../../../workflows/helpers/single-story-deliver.md),
+which state the same constraint from the executor side.
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms
+  latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea
+helps no one. Honest technical disagreement is more valuable than false
+agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the
+boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until
+verification passes. "Seems right" is never sufficient — there must be evidence
+(passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode
+   processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't
+   skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve
+   `idea-refinement` → `spec-driven-development` → `planning-and-task-breakdown`
+   → `incremental-implementation` → `test-driven-development` →
+   `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's
+   no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```text
+1. idea-refinement                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. incremental-implementation  → Build slice by slice
+6. test-driven-development     → Prove each slice works
+7. code-review-and-quality     → Review before merge
+8. git-workflow-and-versioning → Clean commit history
+9. documentation-and-adrs      → Document decisions
+10. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need:
+`debugging-and-error-recovery` → `test-driven-development` →
+`code-review-and-quality`.
+
+## Quick Reference
+
+| Phase  | Skill                         | One-Line Summary                                                  |
+| ------ | ----------------------------- | ----------------------------------------------------------------- |
+| Define | idea-refinement               | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development       | Requirements and acceptance criteria before code                  |
+| Plan   | planning-and-task-breakdown   | Decompose into small, verifiable tasks                            |
+| Build  | incremental-implementation    | Thin vertical slices, test each before expanding                  |
+| Build  | context-engineering           | Right context at the right time                                   |
+| Build  | frontend-ui-engineering       | Production-quality UI with accessibility                          |
+| Build  | api-and-interface-design      | Stable interfaces with clear contracts                            |
+| Verify | test-driven-development       | Failing test first, then make it pass                             |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification                      |
+| Verify | debugging-and-error-recovery  | Reproduce → localize → fix → guard                                |
+| Review | code-review-and-quality       | Five-axis review with quality gates                               |
+| Review | security-and-hardening        | OWASP prevention, input validation, least privilege               |
+| Review | performance-optimization      | Measure first, optimize only what matters                         |
+| Ship   | git-workflow-and-versioning   | Atomic commits, clean history                                     |
+| Ship   | ci-cd-and-automation          | Automated quality gates on every change                           |
+| Ship   | documentation-and-adrs        | Document the why, not just the what                               |
+| Ship   | shipping-and-launch           | Pre-launch checklist, monitoring, rollback plan                   |