bigpowers 2.1.3 → 2.3.0

package/.pi/prompts/inspect-quality.md

@@ -0,0 +1,105 @@
+---
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions "QA session".
+---
+
+
+# Inspect Quality
+> **HARD GATE** — **HARD GATE** — Quality metrics (coverage, lint, cyclomatic complexity, security scans) must be monitored. If a metric degrades, surface it as a blocker. Do NOT accept regressions.
+
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and log each issue to `specs/bugs/registry.yaml` with a structured, durable format.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2–3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to log, move on.
+
+### 2. Explore the codebase in the background
+
+Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE.md` if present)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+### 3. Assess scope: single issue or breakdown?
+
+Break down when:
+
+- The fix spans multiple independent areas
+- There are clearly separable concerns that could be worked on in parallel
+- The user describes something with multiple distinct failure modes
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. Log to specs/bugs/registry.yaml
+
+Append the issue to `specs/bugs/registry.yaml`. Create the `specs/bugs/` directory if it doesn't exist.
+
+#### registry.yaml format
+
+The file maintains a Markdown table with the following columns (derived from structured audit practice):
+
+| Field | Description |
+|-------|-------------|
+| `bug_id` | `BUG-YYYY-MM-DDTHHMMSS` |
+| `date` | `YYYY-MM-DD` |
+| `severity` | `critical` / `high` / `medium` / `low` |
+| `priority` | `p0` / `p1` / `p2` / `p3` |
+| `scope` | kebab-case area (e.g. `auth`, `checkout`) |
+| `what_happened` | actual behavior (user-facing terms) |
+| `what_expected` | expected behavior |
+| `steps_to_reproduce` | numbered steps |
+| `root_cause` | one-line hypothesis |
+| `files_changed` | filled in after fix |
+| `approach` | filled in after fix |
+| `risk_level` | `low` / `medium` / `high` |
+| `new_tests` | count (filled in after fix) |
+| `type_check` | `pass` / `fail` (filled in after fix) |
+| `lint` | `pass` / `fail` (filled in after fix) |
+| `commit_type` | `fix` / `fix!` / `feat` (filled in after fix) |
+| `release_type` | `patch` / `minor` / `major` (filled in after fix) |
+| `commit_message` | Conventional Commits message (filled in after fix) |
+| `follow_ups` | semicolon-separated follow-up items |
+| `file` | path to detailed `specs/bugs/BUG-*.md` (filled in by investigate-bug) |
+| `status` | `open` / `in-progress` / `fixed` / `wont-fix` |
+
+When a bug is fixed (via `validate-fix`), update the relevant row with the resolution fields.
+
+#### Issue body (for context below the table)
+
+For each bug, also append a detail section:
+
+```markdown
+### BUG-YYYY-MM-DDTHHMMSS: [short title]
+
+**What happened:** [actual behavior, plain language]
+**What I expected:** [expected behavior]
+**Steps to reproduce:**
+1. [Step 1]
+2. [Step 2]
+
+**Additional context:** [domain-language observations, no file paths]
+```
+
+#### Rules for all entries
+
+- **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE.md` if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+
+### 5. Continue the session
+
+After logging, ask: "Next issue, or are we done?" Keep going until the user says done. Each issue is independent — don't batch them.

package/.pi/prompts/investigate-bug.md

@@ -0,0 +1,117 @@
+---
+description: Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions "triage", or wants to plan a fix.
+---
+
+
+# Investigate Bug
+
+**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
+
+Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
+
+## Process
+
+### 0. Read previous bug history
+
+Before starting diagnosis:
+
+1. Read `specs/bugs/registry.yaml` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
+2. If a relevant prior bug is found, read the corresponding `specs/bugs/BUG-*.md` file to understand previous root cause analysis and fix approach.
+3. Note in your investigation whether this is a recurrence, a related issue, or novel.
+
+### 1. Capture the problem
+
+Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"
+
+Do NOT ask follow-up questions yet. Start investigating immediately.
+
+### 2. Explore and diagnose (4-phase RCA)
+
+Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
+
+Also look at:
+- Recent changes to affected files (`git log --oneline <file>`)
+- Existing tests (what's tested, what's missing)
+- Similar patterns elsewhere in the codebase that work correctly
+
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
+### 3. Identify the fix approach
+
+Based on your investigation, determine:
+
+- The minimal change needed to fix the root cause
+- Which modules/interfaces are affected
+- What behaviors need to be verified via tests
+- Whether this is a regression, missing feature, or design flaw
+- Risk level: Low / Medium / High
+
+### 4. Design TDD fix plan
+
+Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:
+
+- **RED**: Describe a specific test that captures the broken/missing behavior
+- **GREEN**: Describe the minimal code change to make that test pass
+
+Rules:
+- Tests verify behavior through public interfaces, not implementation details
+- One test at a time, vertical slices (NOT all tests first, then all code)
+- Each test should survive internal refactors
+- Include a final refactor step if needed
+- **Durability**: Only suggest fixes that would survive radical codebase changes. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state.
+
+### 5. Write the bug file
+
+Save the investigation and fix plan to `specs/bugs/BUG-NNN-slug.md`. Create the `specs/bugs/` directory if it doesn't exist.
+
+After writing, append a row to `specs/bugs/registry.yaml` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/registry.yaml` if it doesn't exist.
+
+<diagnosis-template>
+
+# BUG-YYYY-MM-DDTHHMMSS: [short title]
+
+## Problem
+
+A clear description of the bug or issue, including:
+- What happens (actual behavior)
+- What should happen (expected behavior)
+- How to reproduce (if applicable)
+
+## Root Cause Analysis
+
+Describe what you found during investigation:
+- The code path involved
+- Why the current code fails
+- Any contributing factors
+- Risk level: Low / Medium / High
+
+Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead.
+
+## TDD Fix Plan
+
+A numbered list of RED-GREEN cycles:
+
+1. **RED**: Write a test that [describes expected behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+2. **RED**: Write a test that [describes next behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+**REFACTOR**: [Any cleanup needed after all tests pass]
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All new tests pass
+- [ ] Existing tests still pass
+
+## Resolution
+
+<!-- filled in by validate-fix -->
+
+</diagnosis-template>
+
+After writing the bug file, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.

package/.pi/prompts/kickoff-branch.md

@@ -0,0 +1,99 @@
+---
+description: Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions "start a branch" or "new worktree".
+---
+
+
+# Kickoff Branch
+
+> **HARD GATE** — Direct work on `main` or `master` is PROHIBITED. Every task MUST start with this skill to create a feature branch or worktree.
+>
+> **HARD GATE** — Do NOT proceed with development until a clean test baseline is verified. If the current base branch is failing tests, stop and fix the baseline before creating a new worktree.
+
+Create an isolated working environment before touching any code. A clean baseline proves tests pass before you start — so any failure you see later was caused by your changes, not pre-existing issues.
+
+## Process
+
+### 1. Confirm task name
+
+Ask if not already known: "What's the name of this feature or task?" Use it as the branch name slug (kebab-case, max 40 chars).
+
+### 2. Anchor on default branch (main or master)
+
+> **HARD GATE** — Kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
+
+```bash
+# Detect default branch
+DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+git checkout "$DEFAULT"
+git pull --ff-only origin "$DEFAULT"   # skip if no remote
+git status                             # working tree MUST be clean
+git log --oneline -5
+```
+
+If working tree is dirty, ask the user to stash or commit first. If not on `$DEFAULT` after checkout, stop and fix before continuing.
+
+### 3. Pre-flight & Conflict Resolution
+
+Before creating the worktree, verify the target environment is clean:
+
+```bash
+# 1. Check for existing directory
+ls -d ../<task-slug> 2>/dev/null
+
+# 2. Check for existing branch
+git branch --list <task-slug>
+
+# 3. Check for "ghost" worktrees (metadata exists but directory is gone)
+git worktree list | grep "<task-slug>"
+```
+
+**Handling Conflicts:**
+- **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
+- **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
+- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata.
+
+### 4. Create worktree + branch
+
+```bash
+# From the main repo root (not another worktree)
+git worktree add ../<task-slug> -b <task-slug>
+cd ../<task-slug>
+```
+
+If the user prefers a branch without a worktree:
+```bash
+git checkout -b <task-slug>
+```
+
+### 4. Verify clean baseline
+
+Run the full test suite and confirm it passes before writing any code:
+
+```bash
+# Use the project's test command from CLAUDE.md or package.json
+npm test    # or: pytest, go test ./..., cargo test, etc.
+```
+
+- [ ] All tests pass
+- [ ] No type errors (`npm run typecheck` or equivalent)
+- [ ] No lint errors (`npm run lint` or equivalent)
+
+If the baseline is broken, **stop and tell the user**. Do not proceed with development on a broken baseline.
+
+### 5. Confirm readiness
+
+Report the baseline result:
+```
+✓ Baseline clean: 42 tests passed, 0 failed
+Branch: <task-slug>
+Worktree: ../<task-slug>
+Ready to develop.
+```
+
+Suggest next skill: `develop-tdd` to start the TDD loop, or `execute-plan` if `specs/release-plan.yaml + epic capsule directories` already exists.
+
+## Handoff
+
+Gate: READY -> next: develop-tdd
+Writes: state.yaml handoff.next_skill = develop-tdd

package/.pi/prompts/map-codebase.md

@@ -0,0 +1,70 @@
+---
+description: "Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does."
+---
+
+
+# Map Codebase
+
+Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
+
+> **Use this vs survey-context:** `map-codebase` BUILDS the tech-stack doc by scanning the codebase from scratch. `survey-context` READS existing specs/tech-architecture docs without re-deriving them. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
+> **HARD GATE** — Cold analysis only. Do NOT assume architectural patterns without reading the code. If the codebase structure surprises you, call out the delta.
+
+## Process
+
+### 1. Identify Core Stack & Dependencies
+- Scan `package.json`, `Cargo.toml`, `requirements.txt`, etc.
+- Identify primary framework, runtime, and critical libraries (ORM, Auth, State, UI).
+- Note version constraints and any deprecated or unusual dependencies.
+
+### 2. Map High-Level Architecture
+- Identify the entry points (CLI, Web, API).
+- Map the primary data flow (e.g., Controller → Service → Repository).
+- Identify where business logic lives vs. where I/O lives.
+- Look for established patterns (e.g., hexagonal, layered, feature-folders).
+
+### 3. Analyze "Gray Areas" (The "How")
+Search for patterns and anti-patterns in these categories:
+- **Error Handling:** Are exceptions caught early or bubbled? Is there a global error handler? Are error messages structured?
+- **API Shapes:** Is it REST, GraphQL, or RPC? What is the casing (camelCase, snake_case)? How are responses structured?
+- **Type Safety:** Is it strictly typed? Are there many `any` or `unsafe` blocks? Are interfaces used for DIP?
+- **Observability:** Is there structured logging? Are there health checks? Where do logs go?
+- **Testing:** What is the test coverage strategy? Are mocks used? Where do tests live?
+
+### 4. Identify Planning "Signals"
+Look for signals that will influence upcoming plans:
+- **Consistency Gaps:** "Half the project uses async/await, the other half uses Promises."
+- **Debt Hotspots:** "The `AuthManager` is 1500 lines and handles both JWT and session logic."
+- **Integration Points:** "We need to talk to the Stripe API, but there's no wrapper yet."
+- **Conventions:** "The team always uses functional components over classes."
+
+### 5. Persist to specs/tech-architecture/tech-stack.md
+Compile all findings into `specs/tech-architecture/tech-stack.md`. This file serves as the project's "Long-Term Memory".
+
+```markdown
+# Project Context
+
+## Stack
+- [Framework/Language]
+- [Key Libraries]
+
+## Architecture
+- [Pattern Description]
+- [Data Flow]
+
+## Conventions (Observed)
+- [Error Handling Pattern]
+- [API Design]
+- [Type System]
+
+## Signals / Active Considerations
+- [Gap 1]
+- [Hotspot 2]
+```
+
+## When to Use
+- When first joining a project.
+- Before a major refactor or architectural change.
+- When `survey-context` reveals a lack of domain knowledge.
+- To refresh `specs/tech-architecture/tech-stack.md` after significant changes.