feat(skills): add performance engineering awareness to pb-plan and pb-build prompts

Absorb key insights from performance audit methodology into the system
prompts for both planning and building phases. All performance checks are
conditional — only applied when tasks touch data access, API endpoints,
or hot paths.

pb-plan (design phase):
- Codebase audit now flags performance-relevant patterns (caching layers,
  query helpers, pagination utilities, batch processing helpers)
- Architecture decisions include brief performance impact assessment for
  data access and hot path decisions
- Architectural Constraints section includes N+1 and over-fetching
  examples as RFC 2119 constraints
- Non-Functional Goals template adds structured fields for database access,
  caching, API payload, and hot paths
- Design template adds 5.8a Performance Impact Assessment table mapping
  decisions to performance characteristics, risks, and mitigations
- Key Principles adds #23: Performance-aware design
- Edge cases section adds performance-aware planning guidance

pb-build (implementation phase):
- Generator workflow adds Performance Sanity Check step (step 9 for
  BDD+TDD, step 8 for TDD-only) checking for N+1, eager loading,
  over-fetching
- Implementer prompt adds 2i-a. Performance Sanity Check section with
  specific checks for loops, eager loading, over-fetching, constraints
- Evaluator prompt adds performance red flags to code quality checks,
  new Check E — Performance Sanity, and performance to verdict format
- Anti-pattern list adds N+1 queries and over-fetching as known
  anti-patterns

Files changed:
- skills/pb-plan/SKILL.md
- skills/pb-plan/references/design_template.md
- skills/pb-plan/references/tasks_template.md
- skills/pb-build/SKILL.md
- skills/pb-build/references/implementer_prompt.md
- skills/pb-build/references/evaluator_prompt.md

Author: Akagi201

skills/pb-build/SKILL.md

@@ -213,7 +213,14 @@ The subagent operates as **Generator** — its sole objective is to make tests p
 
 8. **Architecture Conformance Check** — Confirm implementation matches Architecture Decisions.
 
-9. **Scope Check** — Confirm no extra scope beyond the scenario.
+9. **Performance Sanity Check (when applicable)** — For tasks touching data access, API endpoints, or hot paths:
+   - Scan for obvious N+1 query patterns (looping with individual DB calls)
+   - Verify eager loading or batching is used where the design specifies it
+   - Check that API responses don't over-fetch beyond what the scenario requires
+   - If the design includes performance constraints (latency, throughput), verify the implementation doesn't violate them
+   - Skip this step for tasks that don't touch data access or hot paths
+
+10. **Scope Check** — Confirm no extra scope beyond the scenario.
 
 ##### For TDD-Only Tasks (Non-Scenario)
 
@@ -224,7 +231,8 @@ The subagent operates as **Generator** — its sole objective is to make tests p
 5. **REFACTOR** — Clean up. Re-run affected tests.
 6. **Runtime Verification (when applicable)** — Run runtime checks.
 7. **Architecture Conformance Check** — Verify design conformance.
-8. **Scope Check** — Verify scope compliance.
+8. **Performance Sanity Check (when applicable)** — Same checks as BDD+TDD tasks above.
+9. **Scope Check** — Verify scope compliance.
 
 **The Generator MUST end its output with exactly this signal (no extra text after it):**
 
@@ -617,6 +625,8 @@ The Evaluator should watch for these common agent mistakes:
 | **Speculative features** | Adding caching, validation, notifications to a "save preferences" request | Build only what was asked; add later when needed |
 | **Vague success criteria** | "I'll review and improve the code" | "Write test for bug X → make it pass → verify no regressions" |
 | **Style drift** | Changing quote style, whitespace, or return logic while adding logging | Match existing code style exactly |
+| **N+1 queries** | Looping with individual DB calls instead of batch/eager loading | Use eager loading, batch queries, or prefetch where the design specifies |
+| **Over-fetching** | Returning all columns/fields when the consumer only needs a few | Return only required fields; document why wider payload is justified |
 
 ---
 

skills/pb-build/references/evaluator_prompt.md

@@ -66,6 +66,7 @@ Analyze the git diff against the task contract.
    - Are external dependencies routed through interfaces or abstract classes (DIP)?
    - Does each module/class have a single responsibility (SRP)?
    - Are the `Architecture Decision Snapshot` constraints from the project preserved?
+   - Are performance-related design decisions honored (e.g., eager loading, batch queries, field selection)?
 
 3. **Code quality red flags:**
    - Hardcoded values that should be configurable
@@ -79,6 +80,11 @@ Analyze the git diff against the task contract.
      - Missing `ponytail:` comment on deliberate simplifications
      - Code that could be 1 line but isn't
    - Missing error handling for external calls
+   - **Performance red flags** (when the task touches data access or hot paths):
+     - N+1 query patterns: loops with individual DB calls where batching/eager loading would work
+     - Over-fetching: returning all columns/fields when the consumer only needs a subset
+     - Missing eager loading where the design specifies it
+     - Unbounded result sets without pagination
 
 4. **Dependency integrity:**
    - Does this task correctly use outputs from previously completed tasks?
@@ -154,6 +160,20 @@ Apply the ponytail ladder to the diff:
 
 **Output:** Flag any over-engineering found. Each issue should reference the specific ponytail ladder rung violated.
 
+### Check E — Performance Sanity (when applicable)
+
+For tasks that touch data access, API endpoints, or hot paths:
+
+1. **N+1 detection:** Are there loops making individual DB/API calls where batching or eager loading would work?
+2. **Eager loading:** Does the implementation use eager loading or joins where the design specifies it?
+3. **Over-fetching:** Do API responses return only what the scenario requires, or are extra fields included without justification?
+4. **Unbounded results:** Are there queries without pagination or limits that could return unbounded result sets?
+5. **Performance constraints:** If the design includes latency/throughput targets, does the implementation obviously violate them?
+
+**Skip** this check for tasks that don't touch data access, API boundaries, or hot paths.
+
+**Output:** List any performance issues found with file:line references.
+
 ---
 
 ## Verdict
@@ -169,6 +189,7 @@ After completing all three checks, output your verdict in exactly one of these f
 - Scope: [Confirmed clean / note any concerns]
 - Architecture: [Conformance confirmed / specific violations]
 - Code quality: [Clean / issues found and resolved]
+- Performance: [Clean / N+1 or over-fetching issues found and resolved / N/A for non-data tasks]
 
 ### Live Verification
 - [Method used: Playwright MCP / HTTP MCP / CLI]

skills/pb-build/references/implementer_prompt.md

@@ -163,6 +163,16 @@ Output this analysis enclosed in `<error_analysis>` tags before rewriting code.
 - Confirm external dependencies still flow through interfaces or abstract classes when required.
 - If you discover the planned architecture no longer fits, stop and raise a Design Change Request instead of improvising a new pattern mid-build.
 
+#### 2i-a. Performance Sanity Check (when applicable)
+
+For tasks touching data access, API endpoints, or hot paths:
+
+1. **N+1 detection:** Scan for loops that make individual DB/API calls where batching or eager loading would work.
+2. **Eager loading:** If the design specifies eager loading or joins, verify they are present.
+3. **Over-fetching:** Check that API responses return only what the scenario requires.
+4. **Performance constraints:** If the design includes latency/throughput targets, verify the implementation doesn't obviously violate them.
+5. **Skip** this check for tasks that don't touch data access, API boundaries, or hot paths.
+
 #### 2j. Scope Check
 
 - Confirm implementation matches the task contract and does not include extra scope.

skills/pb-plan/SKILL.md

@@ -110,6 +110,7 @@ Subagent rules:
    - Existing abstractions (base classes, interfaces, protocols) to extend
    - Shared infrastructure (database connections, HTTP clients, cache layers)
    - Similar prior implementations that establish patterns to follow
+   - **Performance-relevant patterns:** Existing caching layers, query optimization helpers, connection pools, pagination utilities, or batch processing helpers
    **This audit is mandatory.** List reusable components in `design.md` Section 3.3 and reference them in `tasks.md` task context.
 
 6. **Extract the `Architecture Decision Snapshot`** — this is mandatory whenever the repo has `AGENTS.md` or architecture-oriented docs:
@@ -119,6 +120,7 @@ Subagent rules:
    - All external dependencies must be routed **through interfaces or abstract classes** in the plan unless the existing repo explicitly establishes a different seam.
    - Reuse existing repo decisions when available; add new decisions only when the requirement creates a genuine gap.
    - **Apply the ponytail ladder** when evaluating patterns: prefer stdlib/native solutions over custom implementations. An interface with one implementation is a factory for one product — skip it. A config for a value that never changes is a constant — hardcode it.
+   - **Performance impact assessment:** For any architectural decision that touches data access, API boundaries, or hot paths, briefly note the expected performance characteristic (e.g., "O(n) queries acceptable for n<100" or "requires lazy loading to avoid N+1"). Do not write full performance specs — just flag the obvious wins and risks.
 
 7. **Audit coding standards and simplification boundaries** — determine which style and maintainability rules the eventual implementation must follow:
    - Infer language- and framework-specific standards from `AGENTS.md`, `CLAUDE.md`, and the live codebase. Only apply standards that are relevant to the current repo; do not copy unrelated JavaScript or React rules into Python work.
@@ -253,6 +255,8 @@ Write a **compact** design doc to `specs/<spec-dir>/design.md`. Only include sec
 - Database interactions **MUST** use the existing ORM layer; raw SQL queries **MUST NOT** be introduced because they bypass the query builder's injection protection.
 - API responses **SHOULD** maintain <200ms p99 latency; if exceeded, the task **MUST** include performance optimization before marking done.
 - If an unhandled edge case is encountered, the Builder **MUST** halt and file a DCR; it **MUST NOT** silently fabricate error handling.
+- Database queries **MUST NOT** introduce N+1 patterns; the Builder **SHOULD** use eager loading or batch queries where the data access pattern involves related entities.
+- API responses **SHOULD** avoid over-fetching; return only fields the consumer needs, or document why a wider payload is justified.
 
 ## Behavior Traceability Matrix
 
@@ -339,6 +343,12 @@ stateDiagram-v2
 
 Read `references/design_template.md` and fill every section fully. Write the result to `specs/<spec-dir>/design.md`.
 
+**Performance awareness for full mode:** When filling the Non-Functional Goals section, explicitly consider:
+- **Database access patterns:** Identify whether the feature introduces new queries and whether they risk N+1 or missing indexes.
+- **Caching opportunities:** Note if responses or computations are cacheable, and whether existing caching infrastructure can be reused.
+- **API payload size:** Flag if the feature returns large datasets and whether pagination or field selection is needed.
+- **Hot path identification:** If the feature touches code that runs frequently (request handlers, loops, parsers), note expected throughput requirements.
+
 ### Step 5a: Output `tasks.md` — Lightweight Mode (< 50 words)
 
 Write a **scenario-driven task list** to `specs/<spec-dir>/tasks.md`. Tasks are organized by Feature scenarios, not by module. Even in lightweight mode, task IDs must remain in `Task X.Y` format so `pb-build` can track state reliably:
@@ -513,6 +523,7 @@ Please review the design and tasks. When ready, run /pb-build <feature-name> to
 20. **Truthfulness over fluency.** If information is missing, state assumptions explicitly instead of fabricating specifics.
 21. **Deterministic output quality.** Final docs should be implementation-ready, with no template artifacts left behind.
 22. **No speculative architecture.** If a design component cannot be traced to a Feature scenario, remove it. Avoid building what isn't requested.
+23. **Performance-aware design.** When architecture decisions touch data access, API boundaries, or hot paths, note the expected performance characteristic. Flag N+1 risks, over-fetching, and missing indexes during the codebase audit. Do not write full performance specs — just identify the obvious wins and risks.
 
 ---
 
@@ -547,3 +558,4 @@ Please review the design and tasks. When ready, run /pb-build <feature-name> to
 - **High-variance logic with small example space:** Add property-test planning rather than relying only on hand-written examples.
 - **Parser/protocol/unsafe work:** Treat fuzz planning as required unless you can justify why crash-safety risk is absent.
 - **Performance-sensitive work:** Add benchmark planning only when the requirement or codebase indicates performance is part of the contract.
+- **Performance-aware planning:** When the feature touches data access, API boundaries, or hot paths, flag obvious N+1 risks, over-fetching, and missing indexes during the codebase audit. Include performance constraints in `design.md` §Architectural Constraints when they are part of the contract. Do not write full performance specs for every task — just identify the obvious wins and risks.

skills/pb-plan/references/design_template.md

@@ -72,7 +72,11 @@
 
 > Performance, reliability, security, observability, etc.
 
-- **Performance:** ...
+- **Performance:**
+  - **Database access:** [Identify new queries, N+1 risks, index needs]
+  - **Caching:** [Cacheable responses, existing cache infrastructure reuse]
+  - **API payload:** [Over-fetching risks, pagination needs]
+  - **Hot paths:** [Throughput requirements for frequently-executed code]
 - **Reliability:** ...
 - **Security:** ...
 
@@ -242,6 +246,14 @@ graph LR
 - **DIP Check:** Identify the seams where dependencies must be inverted.
 - **Dependency Injection Plan:** All external dependencies should flow through interfaces or abstract classes unless the repo already has a documented alternative seam.
 
+### 5.8a Performance Impact Assessment
+
+> For architectural decisions that touch data access, API boundaries, or hot paths. Keep it brief — flag obvious wins and risks, not a full performance spec.
+
+| Decision | Performance Characteristic | Risk | Mitigation |
+| :--- | :--- | :--- | :--- |
+| [e.g., "Use ORM for user queries"] | [e.g., "O(n) for n<100 users"] | [e.g., "N+1 if relations not eager-loaded"] | [e.g., "Use select_related/joinedload"] |
+
 ### 5.9 BDD/TDD Strategy
 
 > Describe how this feature will use outside-in development. Define the business-facing Gherkin loop and the supporting TDD loop.

skills/pb-plan/references/tasks_template.md

@@ -26,6 +26,7 @@
 - **Behavior Preservation Rule:** State whether each task preserves existing behavior or intentionally changes it; validate that with scenario and regression coverage.
 - **Simplification Rule:** Apply the ponytail ladder (YAGNI → stdlib → native → existing dep → one-liner → minimum code) at every implementation decision. Mark deferrals with `ponytail:` comments naming the ceiling and upgrade path.
 - **Clarity Guardrail:** Avoid planning dense or clever rewrites; where relevant, avoid nested ternary operators in favor of clearer branching.
+- **Performance Guardrail:** For tasks touching data access or hot paths, the task context should note expected query patterns and any N+1 or over-fetching risks identified during planning.
 - **Phase 1: BDD Harness & Scaffolding** — Feature files, runner setup, task skeletons
 - **Phase 2: Scenario Implementation** — Primary behavior implemented via TDD
 - **Phase 3: Integration & Features** — Connecting pieces, end-to-end
@@ -186,3 +187,4 @@
 6. [ ] **Runtime-Evidenced (when applicable):** Runtime logs and health/probe results are captured, or `N/A` is explicitly justified.
 7. [ ] **Behavior-Preserved or Documented:** The task confirms behavior preservation or documents the intentional behavior change.
 8. [ ] **Simplified Responsibly:** Cleanup stayed within the planned scope and improved readability rather than introducing clever compaction.
+9. [ ] **Performance-Sound (when applicable):** No obvious N+1 queries, over-fetching, or missing eager loading for tasks touching data access or hot paths; or `N/A` is explicitly justified.