{
  "evals": [
    {
      "name": "should-trigger-fresh-onboarding",
      "prompt": "I need to set up this boilerplate for the Curacity project. Backend is Node.js + Express, frontend is React. Start by discovering the architecture.",
      "expected_behavior": "Activates project-discovery. Confirms scope (Fresh onboarding). Begins Phase 1: Constitution -- asks for repo paths/access, detects stack, produces project-connection, then proceeds through project-assessment, business-model, domain-glossary. Waits for confirmation between phases before advancing.",
      "category": "positive"
    },
    {
      "name": "should-redirect-business-data-map-regeneration",
      "prompt": "Generate the business-data-map.md for this project. Look at the source code and the database.",
      "expected_behavior": "Does NOT generate the map inside this skill and does NOT claim to own it. Redirects to `project-context` mode `data` (legacy alias `/business-data-map`), which is where the entity/flow/state-machine extraction lives. May state which discovery artifacts that mode depends on, and offer to run Phase 1 + Phase 3 first if `.context/` has no project-config or infrastructure yet. Does not reference a context-generators file: this skill has no such reference.",
      "category": "positive"
    },
    {
      "name": "should-redirect-api-architecture-request",
      "prompt": "The api-architecture.md is stale. Regenerate it with the current endpoints.",
      "expected_behavior": "Does NOT regenerate api-architecture.md inside this skill. Either declines (if invoked) or activates only to redirect: explains the split — `bun run api:sync` for technical endpoint sync (TypeScript types from OpenAPI) and `project-context` mode `api` (legacy alias `/business-api-map`) for the business angle (auth flows, critical paths). Does not point at a context-generators file: that reference no longer exists, and the deferral note now lives in this skill's SKILL.md routing table.",
      "category": "positive"
    },
    {
      "name": "should-not-trigger-write-e2e-test",
      "prompt": "Write an E2E test for the login flow.",
      "expected_behavior": "Does NOT activate project-discovery. Should route to test-automation (KATA test authoring). project-discovery is for onboarding and context generation, not writing test code.",
      "category": "negative"
    },
    {
      "name": "should-not-trigger-kata-concept-question",
      "prompt": "What is KATA and how does it work?",
      "expected_behavior": "Does NOT activate project-discovery. General conceptual question answerable without a skill. project-discovery is for reverse engineering a target project; KATA adaptation belongs to `/adapt-framework`, and neither exists to explain the framework in the abstract.",
      "category": "negative"
    },
    {
      "name": "should-not-trigger-run-regression",
      "prompt": "Run the regression suite.",
      "expected_behavior": "Does NOT activate project-discovery. Should route to regression-testing. project-discovery never executes test suites.",
      "category": "negative"
    }
  ]
}

# Phase 1 — Constitution

> Read this when running any Phase 1 sub-step (Project Connection, Project Assessment, Business Model, Domain Glossary), or when the Phase 1 section of SKILL.md §Workflow points here.

The first phase of project discovery. Goal: make the project legible. Produces four outputs, in this exact order. Each sub-step reads the previous one's output.

```
1. Project Connection    -> .context/project-config.md
2. Project Assessment    -> AGENTS.md §Project Assessment + .context/risk-assessment.md (if HIGH risks)
3. Business Model        -> .context/business/business-model.md
4. Domain Glossary       -> .context/business/domain-glossary.md
```

Rule: no sub-step starts until the previous one's file exists on disk.

---

## 1. Project Connection

### Inputs to gather

| Priority | Information | How to get it |
|----------|-------------|---------------|
| HIGH | Repository URLs | Ask user, or `gh repo view <owner/repo>` |
| HIGH | Tech stack | Detect from `package.json` / `pyproject.toml` / `go.mod` etc. |
| MEDIUM | Environment URLs (dev/staging/prod) | Read `.env.example`, `docker-compose.yml`, CI secrets inventory, then ask |
| MEDIUM | Issue tracker | Ask user ("Jira / Linear / GitHub Issues?") |
| LOW | Team contacts | Ask only if needed to unblock access |

Ask incrementally -- never dump all five questions up front.

### Detection commands

```bash
# Repository shape
gh repo view <owner/repo> --json name,description,defaultBranchRef
ls -la <repo-root>
find <repo-root> -maxdepth 2 -name "docker-compose*.yml" -o -name "Dockerfile" -o -name "turbo.json" -o -name "pnpm-workspace.yaml"

# JS / TS stack
cat <repo-root>/package.json | jq '.dependencies, .devDependencies, .scripts'

# Python stack
cat <repo-root>/pyproject.toml
cat <repo-root>/requirements.txt

# Framework fingerprints (file-based)
ls <repo-root>/next.config.* <repo-root>/angular.json <repo-root>/vite.config.* <repo-root>/nest-cli.json 2>/dev/null

# CI/CD
ls <repo-root>/.github/workflows/
gh workflow list -R <owner/repo>
```

### Output: `.context/project-config.md`

```markdown
# Project Configuration

> Project: {{PROJECT_NAME}}
> Generated: <YYYY-MM-DD>

## Repositories

| Repository | URL | Branch | Purpose |
|------------|-----|--------|---------|
| {{FRONTEND_REPO}} | <url> | main | Web application |
| {{BACKEND_REPO}}  | <url> | main | API services |

## Tech Stack

### Frontend
- Framework: <name + version>
- Language: <TypeScript / JavaScript / ...>
- Styling: <Tailwind / styled-components / ...>
- State: <Zustand / Redux / Context / ...>

### Backend
- Framework: <Express / NestJS / FastAPI / ...>
- Language: <TypeScript / Python / Go / ...>
- ORM: <Prisma / TypeORM / SQLAlchemy / ...>

### Database
- Type: <PostgreSQL / MySQL / MongoDB / ...>
- Provider: <Supabase / AWS RDS / Atlas / ...>
- Access: <MCP name / connection string source>

### Infrastructure
- Cloud: <Vercel / AWS / GCP / Azure / ...>
- CI/CD: <GitHub Actions / CircleCI / ...>
- Monitoring: <Sentry / DataDog / ...>

## Environments

| Environment | URL | Purpose | Access |
|-------------|-----|---------|--------|
| Local       | {{environments.local.web_url}}   | Dev | Direct |
| Staging     | {{environments.staging.web_url}} | Pre-prod testing | <VPN? Auth?> |
| Production  | <URL> | Live | Read-only |

## Tools and Access

- Issue tracker: <Jira / Linear / GitHub Issues> -- resolved via [ISSUE_TRACKER_TOOL]
- Project key: {{PROJECT_KEY}}
- Database: resolved via [DB_TOOL]
- Docs: <Confluence / Notion / GitHub Wiki>

## Access Checklist

- [ ] Repository read access
- [ ] Database access (MCP or direct)
- [ ] Issue tracker access
- [ ] Staging environment reachable
- [ ] CI/CD visibility

## Discovery Gaps

- [ ] <item you could not verify, where to get the source of truth>
```

### Completion criteria

- `.context/project-config.md` exists.
- At least Repositories + Tech Stack + Environments sections are filled.
- Access Checklist has known state per row (checked or flagged as blocker in Discovery Gaps).

---

## 2. Project Assessment

Assess current testing maturity to decide where to invest effort in later phases.

### Testing maturity scale

| Score | State | Indicators |
|-------|-------|------------|
| 0 | None | No test files, no test scripts |
| 1 | Basic | Some unit tests, no integration |
| 2 | Moderate | Unit + some integration, manual E2E |
| 3 | Good | Unit + integration + some E2E automation |
| 4 | Mature | Full coverage, CI integration, monitoring |

### Documentation scale

| State | Indicators |
|-------|------------|
| Minimal | Only basic README |
| Partial | README + some API docs |
| Good | README + API + setup guide |
| Complete | All above + architecture + contributing |

### CI/CD maturity

| Level | Indicators |
|-------|------------|
| None | No workflows |
| Basic | Build only |
| Moderate | Build + lint |
| Good | Build + lint + tests |
| Mature | Build + lint + tests + deploy + monitoring |

### Commands

```bash
# Test inventory
find <repo-root> -type f \( -name "*.test.*" -o -name "*.spec.*" \) | wc -l
ls -d <repo-root>/{tests,test,__tests__,spec,e2e,integration} 2>/dev/null

# Quality tools
cat <repo-root>/package.json | jq '.devDependencies | with_entries(select(.key | test("eslint|prettier|husky|lint-staged|typescript")))'
ls <repo-root>/tsconfig.json <repo-root>/.eslintrc* <repo-root>/.prettierrc* <repo-root>/.husky 2>/dev/null

# CI test jobs
grep -l "test\|jest\|vitest\|playwright" <repo-root>/.github/workflows/*.yml

# Secret leak sweep (report only -- do not fix secrets in discovery)
grep -rE "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"]" <repo-root>/src
```

### Risks to flag

| Risk | Detection | Impact |
|------|-----------|--------|
| No tests | Empty test dirs | HIGH |
| Outdated dependencies | `npm audit` / `pip-audit` warnings | MEDIUM |
| No type checking | Missing `tsconfig.json` on a TS project | MEDIUM |
| Hardcoded secrets | grep hits above | HIGH |
| No CI | Missing workflow files | MEDIUM |

### Output

Append to `AGENTS.md` (the canonical file — `AGENTS.md` is a symlink to it) in a `## Project Assessment (Phase 1)` block:

```markdown
## Project Assessment (Phase 1)

Assessment Date: <YYYY-MM-DD>

### Testing Maturity: <score>/4
- Current state: <None / Basic / Moderate / Good / Mature>
- Test files: <count>
- Frameworks: <Jest, Vitest, Playwright, ...>
- Coverage: <unknown / X%>

### Documentation State: <Minimal / Partial / Good / Complete>
- README: <yes/no>
- API docs: <yes/no>
- Architecture: <yes/no>
- Setup guide: <yes/no>

### Code Quality
- [ ] ESLint: <configured / missing>
- [ ] Prettier: <configured / missing>
- [ ] TypeScript: <strict / loose / none>
- [ ] Pre-commit hooks: <configured / missing>

### CI/CD Maturity: <None / Basic / Moderate / Good / Mature>

### Identified Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| <name> | HIGH/MEDIUM/LOW | <action> |

### Phase Prioritization

- Phase 1: <Normal / Extended> -- <reason>
- Phase 2: <Normal / Extended> -- <reason>
- Phase 3: <Normal / Skip> -- <reason>
- Phase 4: <Normal / Extended> -- <reason>

### Blockers
- [ ] <blocker + action>
```

If HIGH risks exist, also write `.context/risk-assessment.md` with per-risk Severity, Description, Impact, Recommendation, Owner.

### Completion criteria

- `## Project Assessment (Phase 1)` section present in canonical `AGENTS.md`.
- HIGH risks (if any) captured in `.context/risk-assessment.md`.

---

## 3. Business Model Discovery

Produce a Business Model Canvas by **discovering** from the code, not by inventing.

### Mindset shift

- Original (product creation): "Define your value proposition."
- Discovery: "What value proposition does this product already deliver?" Every statement in the output must cite a source in the repo.

### Discovery commands

```bash
# Product overview
cat <repo-root>/README.md

# User types / roles
grep -rE "\b(role|userType|UserRole|userRole)\b" --include="*.ts" --include="*.js" --include="*.py" <repo-root>/src | head -50

# Features -- main routes
ls <repo-root>/src/app <repo-root>/src/pages 2>/dev/null
ls <repo-root>/src/api <repo-root>/src/routes <repo-root>/src/controllers 2>/dev/null

# Revenue signals
grep -rE "\b(price|subscription|plan|tier|stripe|paypal)\b" --include="*.ts" --include="*.js" <repo-root>/src | head -30
grep -E "stripe|paypal|paddle|lemonsqueezy" <repo-root>/package.json
```

### Output: `.context/business/business-model.md`

Sections (in this order):

1. **Problem Statement** -- 2-3 paragraphs; cite each claim ("Source: README line 12" / "Source: src/app/landing/page.tsx").
2. **Business Model Canvas** -- nine blocks. Only include evidence you actually found; mark unknown blocks as "Unknown -- requires user input".
   - Customer Segments
   - Value Propositions
   - Channels (web, mobile, API, ...)
   - Customer Relationships (self-service, automated, personal)
   - Revenue Streams (mark Unknown if unclear)
   - Key Resources (infra, content, data)
   - Key Activities (map to core features discovered)
   - Key Partners (from `package.json` integrations)
   - Cost Structure (from infra + paid services)
3. **Discovery Gaps** -- explicit list of what you could not find.
4. **QA Relevance** -- one table mapping (Business aspect) -> (Testing implication).
5. **Sources Used** -- provenance list for every claim.

### Quality rules

- Every row has a `Found in:` column. If empty, the row does not get written.
- Confidence level (High / Medium / Low) is required on top of the doc.
- Never copy marketing copy blindly -- if the deployed site says "revolutionary platform", classify it as marketing language and downgrade confidence.

### Completion criteria

- `.context/business/business-model.md` exists.
- At least Customer Segments + Value Propositions + Key Activities + Sources are populated with real evidence.
- Discovery Gaps section lists everything marked Unknown.

---

## 4. Domain Glossary

Extract domain-specific terminology from the codebase. Bridges developer language (`user`, `order`) and business language (Customer, Purchase).

### Discovery commands

```bash
# Entities / models
find <repo-root> -name "*.model.ts" -o -name "*.entity.ts" -o -name "*.schema.ts" -o -name "*.dto.ts"
cat <repo-root>/prisma/schema.prisma 2>/dev/null
ls <repo-root>/src/entities <repo-root>/src/models 2>/dev/null

# Database
[DB_TOOL] List Tables:
  schema: public
  include: columns, types, constraints

# Enums / constants
grep -rE "enum\s+[A-Z][A-Za-z]+" --include="*.ts" <repo-root>/src
grep -rE "export\s+const\s+[A-Z_]+\s*=" --include="*.ts" <repo-root>/src/constants <repo-root>/src/types 2>/dev/null

# Relationships
grep -A2 "@relation" <repo-root>/prisma/schema.prisma 2>/dev/null
grep -B2 -A2 "ManyToOne\|OneToMany\|ManyToMany" <repo-root>/src/entities/*.ts 2>/dev/null

# Business rules
grep -rE "validate|throw new (Error|.+Exception)" --include="*.ts" <repo-root>/src/services <repo-root>/src/domain 2>/dev/null | head -40

# UI labels (i18n)
cat <repo-root>/src/locales/en.json 2>/dev/null
cat <repo-root>/public/locales/en/*.json 2>/dev/null
```

### Output: `.context/business/domain-glossary.md`

Required sections:

1. **Core Entities** -- one subsection per entity with this table:
   ```
   Technical Name | Business Name | Description | Table/Collection | Key Attributes | Found In
   ```
   Plus `Relationships` list (Has many / Belongs to) and a JSON example.
2. **Enumerations and Constants** -- one table per enum: `Value | Business Meaning | Usage Context`. Note file path.
3. **Business Rules** -- one subsection per rule with Description, Entities Affected, Validation, Error Message, Found In. Include a Given/When/Then example.
4. **Entity Relationships Diagram** -- a Mermaid `erDiagram` block.
5. **Terminology Mapping** -- two tables:
   - Technical -> Business terms (`user` -> `Customer`, `order` -> `Purchase`).
   - Abbreviations and acronyms.
6. **Status / State Flows** -- Mermaid `stateDiagram-v2` per stateful entity.
7. **UI Labels Reference** -- form field table and action button table.
8. **Discovery Gaps** -- terms needing clarification.
9. **QA Usage Guide** -- how future test-case authors should use this file.

### Quality rules

- Every entity must include its file path (`Found In` column).
- Enumeration values use the code constant (`PENDING`, `ACTIVE`), not the free text.
- State diagrams are mandatory for entities with more than two states -- QA testing of state transitions depends on this.
- If i18n exists, pull UI labels from i18n files (the real ones shipped), not from component JSX (which may be hardcoded fallbacks).

### Completion criteria

- `.context/business/domain-glossary.md` exists.
- At least all `Core Entities` found in the schema are documented (no skipping).
- One `erDiagram` is present and parses as valid Mermaid.

---

## Phase 1 — exit gate

Before proceeding to Phase 2:

- [ ] `.context/project-config.md` exists and is non-empty.
- [ ] `## Project Assessment (Phase 1)` block present in canonical `AGENTS.md`.
- [ ] `.context/business/business-model.md` exists with real sources cited.
- [ ] `.context/business/domain-glossary.md` exists with at least Core Entities + Relationships Diagram.
- [ ] All Discovery Gaps are listed explicitly (no silent skipping).
- [ ] The user has confirmed "Phase 1 complete, proceed to Phase 2".

Never auto-advance. Phase 2 only starts after explicit user confirmation.

---

## Phase 1 gotchas

- **Ask incrementally.** Do not dump all five Project Connection questions at once -- get repo first, then tech stack, then environments.
- **Credentials:** see SKILL.md §Gotchas "Credentials never live in discovery docs". Point to `.env` keys, never paste secrets.
- **Confidence levels are mandatory.** Business-model discovery especially -- if the README is marketing prose, mark Medium or Low.
- **Do not invent sources.** If something is not in the code, it goes in Discovery Gaps.
- **Monorepo caveat.** If the repo is a monorepo, Tech Stack in project-config lists per-package entries, and Core Entities in the glossary note which package they belong to.
- **Prefer schema over ORM models.** If both exist, the migration file / schema dump is authoritative. ORM models can drift.
- **HIGH risks block progress.** No tests + hardcoded secrets + no CI = stop, fix secrets, re-assess before Phase 2.
- **Extract UI labels from i18n files when they exist.** Component JSX strings may be fallback text; the production label lives in the translation bundle.

# Phase 2 — PRD Discovery

> Read this when running any Phase 2 PRD sub-step (Executive Summary, User Personas, User Journeys), or when the Phase 2 PRD section of SKILL.md §Phases points here.

Produce the Product Requirements Documents by reading the code, not by interviewing stakeholders. Four docs, produced in order. Each one builds on the previous.

```
1. Executive Summary     -> .context/PRD/executive-summary.md
2. User Personas         -> .context/PRD/user-personas.md
3. User Journeys         -> .context/PRD/user-journeys.md
4. Feature Inventory     -> delegated to /business-feature-map command
                            (output: .context/business/business-feature-map.md)
```

Prereqs (from Phase 1): `.context/business/business-model.md` and `.context/business/domain-glossary.md` must exist. Personas link to roles already identified in the glossary; journeys link to features already identified in the business model.

**Mindset**: product discovery, not product creation. Every claim cites a code or doc source. Aspirational language ("will eventually support") belongs in Discovery Gaps, not in the doc body.

---

## 1. Executive Summary

Entry point for anyone learning the product. Must fit in one read.

### Discovery commands

```bash
# Problem + solution
head -80 <repo-root>/README.md
grep -rE "hero|tagline|headline" --include="*.tsx" <repo-root>/src | head -20
cat <repo-root>/src/app/page.tsx <repo-root>/src/pages/index.tsx 2>/dev/null | head -100

# Core features -- navigation + API surface
grep -rE "path\s*:\s*['\"]|href=" --include="*.tsx" <repo-root>/src/components/nav* <repo-root>/src/app/layout* 2>/dev/null
ls <repo-root>/src/app/api <repo-root>/src/pages/api <repo-root>/src/routes 2>/dev/null

# Metrics -- analytics + monitoring
grep -rE "analytics|track|event|metric" --include="*.ts" --include="*.tsx" <repo-root>/src | head -20
grep -E "sentry|datadog|newrelic|prometheus|posthog|amplitude|mixpanel" <repo-root>/package.json

# Target users (feed from Phase 1 glossary + auth code)
grep -rE "role|userType|permission" --include="*.ts" <repo-root>/src/auth <repo-root>/src/middleware 2>/dev/null
```

### Required sections in `.context/PRD/executive-summary.md`

1. **Problem Statement** -- The Challenge (2-3 paragraphs with source quotes) + Current Alternatives (if discoverable).
2. **Solution Overview**
   - Product Vision (one sentence)
   - Core Capabilities table: `# | Feature | Problem Addressed | Evidence (route or component)`
   - Key Differentiators
3. **Success Metrics**
   - Tracked Metrics: `Metric | Type (Adoption/Engagement/Revenue) | Implementation | Source`
   - Inferred KPIs (from features, not real tracking)
   - Unknown Metrics (gaps)
4. **Target Users** -- brief for each persona: System Role + Need + Evidence. Detailed personas go in the next doc.
5. **Product Scope**
   - What's Included (current capabilities)
   - What's Not Included (known limitations)
   - Future Indicators (TODO comments, feature flags, roadmap files)
6. **Discovery Gaps** -- table `Gap | Impact | Suggested Source`.
7. **QA Relevance** -- Critical Testing Areas + Risk Areas.
8. **Document References** -- list of sibling PRD/SRS docs with status.

### Quality rules

- 5 core features max. More than that and the summary becomes useless.
- Tracked Metrics must show the real `track()` / `analytics.event()` call site -- if you only found the SDK import but no usage, it goes under Inferred KPIs.
- Key Differentiators requires real marketing copy or an obvious code mechanism (e.g., "only product that serves X format"). Inventing a differentiator disqualifies the doc.

---

## 2. User Personas

### Mindset

**In existing products, personas are defined by the code, not by research.** The users you document are the roles the system already recognizes. Do not invent demographic personas; extract system roles and map them to goals that match the permissions they have.

### Discovery commands

```bash
# Role definitions
grep -rE "enum\s+\w*Role|type\s+\w*Role|const\s+[A-Z_]*ROLE" --include="*.ts" <repo-root>/src
grep -rE "hasPermission|canAccess|isAdmin|isOwner|requireAuth" --include="*.ts" <repo-root>/src

# DB role column
grep -A20 "model User" <repo-root>/prisma/schema.prisma 2>/dev/null
grep -rE "role|userType|accountType" <repo-root>/prisma/schema.prisma <repo-root>/drizzle/schema.ts 2>/dev/null

# Middleware / guards
grep -rE "middleware|guard|protect|requireRole" --include="*.ts" <repo-root>/src/middleware <repo-root>/src/guards 2>/dev/null

# Role-based UI rendering
grep -rE "role\s*===|isAdmin|canEdit|hasAccess" --include="*.tsx" <repo-root>/src/components

# Role-specific pages
ls <repo-root>/src/app/admin <repo-root>/src/app/dashboard <repo-root>/src/pages/admin 2>/dev/null

# User profile fields (for attribute discovery)
grep -rE "profile|account|UserProfile|AccountInfo" --include="*.tsx" <repo-root>/src/components | head -20
grep -rE "signup|register" --include="*.tsx" <repo-root>/src | head -20
```

### Required sections in `.context/PRD/user-personas.md`

1. **Persona Discovery Summary** -- single overview table: `Persona | System Role | Access Level | Primary Goal`.
2. **Persona N** (one subsection each; 2-4 personas is typical; do not force a fifth):
   - Identity: System Role (`role_value`) + Evidence file + Access Level + Estimated % of Users.
   - Goals (Inferred from Features): `Goal | Supporting Feature | Route/Component`.
   - Pain Points (Inferred from Validation/Errors): `Pain Point | Evidence` (quote the exact error message).
   - Feature Access: `Feature | Access (Full/Limited/None) | Evidence`.
   - User Journey Summary (one-line ASCII flow).
   - Profile Attributes (from User model schema).
   - Representative Quote (inferred, flagged as such).
3. **Role Hierarchy** -- Mermaid `graph TD` if hierarchy exists.
4. **Permission Matrix** -- `Permission | Role1 | Role2 | Role3 | Role4` with check/cross per cell.
5. **Discovery Gaps** -- `Gap | Why It Matters | Question to Ask`.
6. **QA Relevance**
   - Test Account Requirements: `Persona | Test Account | Permissions Needed`.
   - Critical Persona Flows to Test.
   - Edge Cases by Persona.

### Quality rules

- Fewer is better. Two clean personas beat five speculative ones.
- "Representative Quote" is always flagged "(inferred)" -- it is an illustration, not a datapoint.
- Test Account Requirements must map to `.env` keys (`LOCAL_<ROLE>_EMAIL` / `STAGING_<ROLE>_EMAIL`) when such users exist. If not, flag them as needing creation.

---

## 3. User Journeys

### Mindset

Routes are journey steps. Redirects are transitions. Form submit handlers reveal the next step. Map what the user can actually do, then overlay the personas on each journey.

### Discovery commands

```bash
# Route structure
# Next.js App Router:
find <repo-root>/src/app -name "page.tsx" -o -name "page.ts" | sort
find <repo-root>/src/app -name "layout.tsx"
find <repo-root>/src/app -type d -name "\[*\]"       # dynamic segments

# Next.js Pages Router:
find <repo-root>/src/pages -name "*.tsx" -o -name "*.ts" | grep -v "_app\|_document\|api" | sort

# React Router:
grep -rE "<Route\b" --include="*.tsx" <repo-root>/src

# Navigation components
find <repo-root>/src/components -iname "*nav*" -o -iname "*menu*" -o -iname "*sidebar*"
grep -rE "href=|to=" --include="*.tsx" <repo-root>/src/components/layout <repo-root>/src/components/header 2>/dev/null | head -40

# Conditional nav (role-based)
grep -rE "role.*&&|isAdmin.*&&|can.*&&" --include="*.tsx" <repo-root>/src/components

# Multi-step flows
grep -rE "step|wizard|stepper|progress" --include="*.tsx" <repo-root>/src/components
grep -rE "onSubmit.*next|handleNext" --include="*.tsx" <repo-root>/src

# Redirect patterns
grep -rE "redirect\(|router\.(push|replace)" --include="*.ts" --include="*.tsx" <repo-root>/src | head -40
```

### Required sections in `.context/PRD/user-journeys.md`

1. **Route Map** -- three tables:
   - Public Routes (Unauthenticated): `Route | Page | Purpose`.
   - Protected Routes (Authenticated): `Route | Page | Requires (role) | Purpose`.
   - Dynamic Routes: `Pattern | Example | Purpose`.
2. **Journey N** (one per critical flow; 3-5 journeys is ideal):
   - Persona + Goal + Discovered From.
   - Flow Diagram (Mermaid `journey` or `flowchart LR`).
   - Step-by-Step Flow: `Step | Page | Action | Next | Evidence (file:line)`.
   - Error Paths: `Error | Handling | Evidence`.
   - Success Criteria checklist.
3. **Navigation Structure** -- Mermaid `graph LR` grouping Public / Authenticated / Admin subgraphs.
4. **Breadcrumb Patterns** -- `Path | Breadcrumb`.
5. **Critical Paths**
   - Happy Paths (Must Work): `Journey | Start | End | Business Impact`.
   - Unhappy Paths (Must Handle): `Scenario | Expected Behavior | Evidence`.
6. **Discovery Gaps** -- `Flow | Unknown | Question`.
7. **QA Relevance**
   - Critical E2E Test Scenarios: `Priority (P0/P1/P2) | Scenario | Journey Reference`.
   - Suggested Test Data: `Journey | Test User | Prerequisites`.

### Quality rules

- 3-5 journeys is the right number. Fewer means low coverage; more means you are listing every form, not every journey.
- Always include error paths. Happy paths without their unhappy counterparts are incomplete.
- "Evidence" column is required in Step-by-Step Flow. If you cannot cite a file, the step is a guess.
- Do not map journey steps that require user input you have not received (e.g., OTP or 2FA) without flagging them as external-dependency steps.

---

## 4. Feature Inventory — delegated to `/business-feature-map`

Feature inventory work lives in the `/business-feature-map` command, **not** in this phase. After the PRD sections above are complete (Executive Summary, User Personas, User Journeys), invoke `/business-feature-map` to produce `.context/business/business-feature-map.md`.

The command covers the full feature taxonomy: feature catalog by domain (with stable `FEAT-NNN` IDs), CRUD matrix per entity, API endpoint inventory, UI component inventory (forms + dashboards), third-party integrations, feature flags, planned/WIP features, and the QA relevance matrix. Do not duplicate that logic inside this reference.

**Why split?** The feature map is now also useful outside the discovery pipeline (e.g. when only the backlog changes), so it lives as a standalone command that can be re-run on demand without going through the four-phase discovery again. It also keeps phase-2-prd.md focused on the human-readable PRD docs (summary, personas, journeys), with feature taxonomy as a sibling artifact rather than a section.

When the PRD is assembled, link from `executive-summary.md` and `user-journeys.md` to `business-feature-map.md` for the canonical feature list — never paste a feature catalog into those docs.

---

## Phase 2 — PRD exit gate

Before moving to the SRS half of Phase 2:

- [ ] `.context/PRD/executive-summary.md` exists, 5-or-fewer core capabilities, every row has evidence.
- [ ] `.context/PRD/user-personas.md` exists, 2-4 personas, Permission Matrix filled in, test-account mapping to `.env` complete.
- [ ] `.context/PRD/user-journeys.md` exists, Route Map has all three tables filled in, 3-5 journeys each with Evidence column populated, error paths included.
- [ ] `.context/business/business-feature-map.md` exists (produced by the `/business-feature-map` command, NOT by this phase). CRUD matrix complete for every core entity in the glossary, FEAT-NNN IDs assigned.
- [ ] All three PRD docs (executive-summary, user-personas, user-journeys) include a Discovery Gaps section. The feature map has its own gaps section.
- [ ] `## Phase 2 Progress - PRD` block present in `AGENTS.md`, checkmarks on the three in-phase docs + a pointer to `business-feature-map.md`.

Proceed to `phase-2-srs.md` once the gate is met.

---

## Phase 2 — PRD gotchas

- **PRDs are discovery, not creation.** Do not re-scope the product. Describe what it does today; aspirational content goes in Discovery Gaps.
- **Personas = roles.** In existing systems, personas are the roles the authorization code recognizes. Do not invent "Sarah the busy marketer" -- document "admin", "editor", "viewer" with their actual permissions.
- **Journeys need step-level evidence.** Every step row needs a file path. If you cannot cite a file for a step, the step does not exist in the code; it is either a guess or a future feature -- flag accordingly.
- **Feature IDs and the catalog live in `business-feature-map.md`.** Stable `FEAT-NNN` IDs, CRUD matrix, third-party integration call-site rule, feature-flag defaults — all of that is owned by `/business-feature-map`. PRD docs (summary, personas, journeys) link to it instead of re-listing features.
- **Happy paths without error paths are incomplete.** Refuse to ship a journey doc that lists only the success flow. Error handling is half the behavior.
- **Breadcrumb patterns reveal hierarchy.** If a project uses breadcrumbs, their patterns are the canonical nesting model -- prefer them over navigation group names.

# Phase 2 — SRS Discovery

> Read this when producing any of the three SRS artifacts: `architecture.md`, `functional-specs.md`, `non-functional-specs.md`. Phase 2 SRS runs after Phase 2 PRD (serial: PRD establishes scope, SRS encodes it technically).

---

## SRS output structure

All SRS outputs land under `.context/SRS/` and are overwritten on re-run (never appended):

| File | Purpose |
|------|---------|
| `.context/SRS/architecture.md` | System components, data flow, DB schema, external services. C4 + ER diagrams. |
| `.context/SRS/functional-specs.md` | FR-NNN entries derived from services/validators/state machines. |
| `.context/SRS/non-functional-specs.md` | NFR entries for performance, security, reliability, scalability, observability. |

> **API contracts are NOT an SRS output of this skill.** The canonical API contract lives in two places, neither of which is markdown owned by `project-discovery`:
> - **Technical surface** — `api/openapi-types.ts` (generated by `bun run api:sync` from the project's OpenAPI spec). This is the authoritative request/response shape for tests and automation.
> - **Business angle** — `.context/business/business-api-map.md` (produced by the `/business-api-map` command). Auth flows, critical endpoints, architecture behind the API.
>
> Do not create a parallel `.context/SRS/api-contracts.md`; it desynchronises from the spec and duplicates `/business-api-map`. If neither the OpenAPI spec nor `business-api-map.md` exists, treat that as a Discovery Gap and redirect the user to `bun run api:sync` (if a spec URL is reachable) or `/business-api-map` (if not).

Every artifact MUST include a `## Discovery Gaps` section listing unverified claims. Never invent numbers.

---

## 1. Architecture specs

### Discovery process

1. **Component inventory** — map the folder structure to architectural roles:
   - `ls -la <repo>/src/` then drill into `app/`, `pages/`, `components/`, `services/`, `controllers/`, `repositories/`, `modules/`, `features/`.
   - Identify pattern: MVC, Clean/Hexagonal, Feature-based, Modular monolith.
   - Trace imports with grep to confirm dependency direction.

2. **Database schema** — prefer live schema over ORM definitions (ORMs drift):
   - If `[DB_TOOL]` is configured: query `information_schema.tables` and `information_schema.columns` for the target schema (usually `public`).
   - Fallback: read `prisma/schema.prisma`, `src/entities/*.ts` (TypeORM), `src/db/schema.ts` (Drizzle), or raw `schema.sql` / `migrations/`.
   - Capture: tables, primary keys, foreign keys, enum columns, unique constraints, indexes.

3. **External services** — two signals:
   - `.env.example` keys that are NOT framework-owned (not `NODE_ENV`, `DATABASE_URL`, `NEXTAUTH_SECRET`).
   - `grep -r "process\.env\." src/` to see which env vars code actually reads.
   - Client instantiations: `grep -r "new .*Client\|createClient\|\.initialize" src/`.

4. **Security architecture** — auth method (session / JWT / OAuth), password storage (bcrypt/argon2), session lifetime, TLS posture, secret handling, data-at-rest encryption.

### Required sections in `.context/SRS/architecture.md`

- System Overview (pattern, tech stack table)
- C4 Context diagram (Mermaid)
- C4 Container diagram (Mermaid)
- Component Structure (directory layout + responsibility table)
- Database Schema (ER diagram + table detail table + indexes)
- Data Flow (request sequence + auth sequence)
- External Services (dependency table + integration points)
- Security Architecture (authN / authZ / data protection)
- Performance hooks (caching layers, rate limits discovered)
- Discovery Gaps
- QA Relevance (components to test, environment requirements)

### Diagram conventions

- Use `C4Context`, `C4Container`, `erDiagram`, `sequenceDiagram` from Mermaid.
- Keep C4 diagrams to one screenful; split by subsystem if the whole app won't fit.
- ER diagrams: show only FK relationships and primary columns; full column lists belong in the table detail section.

---

## 2. API contracts — delegated (not an SRS output)

This skill no longer produces `.context/SRS/api-contracts.md`. The API contract has two canonical sources, owned by two different tools:

| Angle | Owner | Output | When to use |
|-------|-------|--------|-------------|
| Technical surface (request/response types) | `bun run api:sync` (script: `scripts/sync-openapi.ts`) | `api/openapi-types.ts` + `api/openapi.json` | Every time the spec changes. Consumed by `api/schemas/*.types.ts` facades and by automated tests. |
| Business angle (auth, critical paths, architecture) | `/business-api-map` command | `.context/business/business-api-map.md` | After discovery, re-run whenever auth or critical flows change. |

During Phase 2 SRS, your job is **not** to document endpoints — it is to confirm which of those two sources is available and record the result:

1. **Locate the OpenAPI spec** (authoritative, saves hours):
   - Files: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json`, `api-spec.*`.
   - Generator signals in `package.json`: `swagger-jsdoc`, `@nestjs/swagger`, `fastify-swagger`, `zod-to-openapi`, `drf-spectacular` (Python).
   - Runtime endpoint: try `/api/docs`, `/swagger`, `/openapi.json`, `/api-docs/openapi.json` via `[API_TOOL]`.
   - If present, note the URL / file path in `.context/project-config.md` under "API spec source". `bun run api:sync` will consume it.

2. **If no OpenAPI spec exists**: log it as a Discovery Gap and recommend the user run `/business-api-map` (after discovery completes) to capture at least the auth flow and critical endpoints. Do **not** hand-write `api-contracts.md` — that pattern has been deprecated.

3. **Auth classification** that used to live in `api-contracts.md` now lives either in the backend middleware audit inside `.context/infrastructure/backend.md` (Phase 3) or in `business-api-map.md`. Keep the SRS scope focused on architecture, functional, and non-functional specs.

> **Gotcha**: if `.context/SRS/api-contracts.md` already exists from a previous run of the old skill, flag it to the user and suggest deletion — it will drift from the OpenAPI spec. Do not update it in place.

---

## 3. Functional specs

### Discovery process

1. **Service-layer analysis** — service methods are functional requirements:
   - Find services: `find src -name "*.service.ts" -o -name "*Service.ts"`, or `src/services/`, `src/lib/services/`.
   - Extract public methods: `grep -r "async \|export function\|public " --include="*.service.ts"`.
   - Map service -> API handler -> feature.

2. **Validation rules** — pull literal constraints from schemas:
   - Zod schemas: rule-per-line (`.min(8)`, `.regex(...)`, `.email()`, `.max(...)`).
   - Custom validators: `grep -r "validate\|isValid\|check" src/services/ src/lib/`.
   - DB constraints: `CHECK`, `UNIQUE`, `NOT NULL`, enum columns in migrations / schema.
   - Each constraint is a test case (boundary values + happy path + error path).

3. **State machines** — where workflows live:
   - Enum definitions: `grep -r "enum .*Status\|enum .*State\|type .*Status" src/types/`.
   - Transition logic: `grep -r "status\s*=\s*\|setState\|updateStatus\|transitionTo"` in service files.
   - DB-level: enum columns, trigger functions, check constraints on status transitions.
   - Diagram with `stateDiagram-v2` (Mermaid) — one diagram per entity with a non-trivial state machine.

4. **Edge cases** — every `throw` is a scenario:
   - `grep -r "throw new .*Error\|throw .*Error" src/services/`.
   - Conditional branches: `grep -r "if .*&&\|if .*||" src/services/ | head -30`.
   - Existing tests: `grep -r "it(\|test(\|describe(" src/` — test names reveal scenarios the team already cares about.

### Required sections in `.context/SRS/functional-specs.md`

- Specification Index (FR-NNN ID, feature, category, priority)
- Per FR: Overview table (feature, related PRD section, service/method, evidence path), Functional Requirement (one sentence), Input Specification (field table), Validation Rules (code snippet from schema), Processing Logic (numbered steps + code evidence), Output Specification (success + error responses), Business Rules (BR-NNN table), Edge Cases table
- State Machines section (Mermaid `stateDiagram-v2` per entity + transition table with From/To/Trigger/Guard/Side Effects)
- Business Rules Summary (cross-FR consolidation)
- Validation Rules Catalog (per entity: field / rules / error message)
- Discovery Gaps
- QA Relevance (test case derivation from each FR, boundary value analysis)

### FR numbering

- `FR-001`, `FR-002`, ... sequentially across the whole spec.
- `BR-001`, `BR-002`, ... for business rules (cross-referenced from FRs).
- Preserve IDs across regenerations if possible — downstream tests may reference them.

---

## 4. Non-functional specs

### Discovery process

1. **Performance**:
   - Caching: `grep -r "cache\|redis\|memo" src/`; Next.js `revalidate`, `cache:` options.
   - Timeouts/limits: `grep -r "timeout\|limit\|rateLimit" src/`.
   - DB query shape: `select`, `include`, `take`, `skip` patterns; pagination strategy; N+1 hot spots.
   - Connection pool size: check ORM config (`src/lib/db.ts`, Prisma `DATABASE_URL` pool params, `DATABASE_POOL_SIZE`).

2. **Security**:
   - Auth mechanism: see Architecture section.
   - Headers: `next.config.js` `headers()` function, Helmet config, CSP strings.
   - Input sanitization: `sanitize-html`, `xss`, `DOMPurify`, `validator` usage.
   - Secret handling: `.env` pattern, secret managers (Vercel env, AWS Secrets Manager, Doppler).
   - Package signals: grep `package.json` for `helmet`, `xss`, `csrf`, `bcrypt`, `argon2`.

3. **Reliability**:
   - Error boundaries: `error.tsx` (Next.js App Router), `ErrorBoundary` components.
   - Retry logic: `grep -r "retry\|Retry\|attempt" src/`; look for exponential backoff.
   - Health endpoints: `find src -name "*health*" -o -name "*ready*"`.
   - Logging stack: `winston`, `pino`, `bunyan`, console patterns.
   - External-call resilience: circuit breakers, timeouts around fetch/axios.

4. **Scalability**:
   - Stateless design: no in-memory state, sessions in Redis / JWT / DB.
   - Async processing: queues (`bullmq`, `pg-boss`, `celery`, `sidekiq`), workers, cron handlers.
   - DB scaling: connection pooling, read replicas, sharding (rare).
   - Deployment model: serverless (Vercel / Lambda) vs long-running (Node/Docker) affects scaling assumptions.

5. **Observability**:
   - APM: `@sentry/*`, `@datadog/*`, `newrelic`, `@opentelemetry/*`.
   - Metrics: `prom-client`, custom counters/gauges/histograms.
   - Tracing: OpenTelemetry spans, `trace`, `span` usage.
   - Log shipping: `pino-pretty`, log drains in hosting platform config.

### Required sections in `.context/SRS/non-functional-specs.md`

- NFR Summary (category / implemented / maturity)
- 1. Performance — NFR-PERF-NNN entries (response time, rate limiting, DB optimization, caching)
- 2. Security — NFR-SEC-NNN entries (authN, authZ, headers, input validation, data protection)
- 3. Reliability — NFR-REL-NNN entries (error handling, health checks, retry strategy, graceful degradation)
- 4. Scalability — NFR-SCALE-NNN entries (stateless, DB scaling, async processing, horizontal scaling)
- 5. Observability — NFR-OBS-NNN entries (logging, monitoring, metrics, alerting)
- Compliance (GDPR / SOC2 / HIPAA / PCI-DSS — mark as "Needs Review" if not verifiable)
- Discovery Gaps
- QA Relevance (which NFRs are testable, suggested tools: k6, Artillery, OWASP ZAP)

### NFR entry template

```markdown
### NFR-<CATEGORY>-NNN: <Title>

| Aspect | Value |
|--------|-------|
| **Target** | <measurable or inferred> |
| **Implementation** | <how it is done> |
| **Evidence** | <path:line-range> |

<Details, tables, code snippets as needed>
```

---

## Gotchas

- **Missing OpenAPI is common.** Most repos either lack a spec or have a stale one. Never trust OpenAPI without spot-checking 3-5 endpoints against code. If stale, flag it and generate api-contracts from code anyway.
- **Undocumented internal endpoints.** Admin-only routes, cron handlers, webhook receivers, feature-flag toggles often sit outside the public API surface. Search for `/admin/`, `/internal/`, `/webhook/`, `/cron/` path prefixes.
- **Auth patterns that resist automation.** OAuth with third-party redirects, CAPTCHA-gated login, device-fingerprint MFA — document these and flag them as "needs manual setup" rather than pretending they can be E2E-tested.
- **Validation drift.** Frontend may have its own Zod schemas that differ from backend schemas. Document both and treat the backend as canonical; note the drift.
- **State machines hidden in DB triggers.** Postgres row-level security policies and trigger functions can block state transitions that look legal in code. Check `pg_trigger` and `pg_policies` via `[DB_TOOL]` if the app uses them.
- **Rate limits you cannot verify.** If middleware config references an external service (Upstash, Redis), you may only see "rateLimit = true" without the actual numbers. Record what you can see and list the gap.
- **NFR numbers must be evidenced or flagged.** "P95 < 500ms" with no load test evidence is a Discovery Gap, not a spec. Prefer "Target: [unknown] — inferred from `timeout: 30000` config" over inventing a number.
- **Security posture is never "complete".** A codebase without Helmet is not a failing grade — it's "Helmet not present, CSP not configured — recommend security review". Avoid pass/fail framing.
- **Do not scrape secrets.** If you stumble onto hard-coded keys in the source, do NOT paste them into the SRS. Document "hard-coded secret detected at `<path>`" as a security finding. Also see SKILL.md §Gotchas for the broader credential policy when reading `.env` and `project-config.md`.
- **Paginate entity lists.** For large schemas (50+ tables) split the ER diagram into subsystem-level diagrams. One giant diagram is unreadable.

---

## Deliverables checklist

Before the Phase 2 SRS completion gate, verify:

- [ ] `.context/SRS/architecture.md` exists with C4 context, C4 container, ER diagram, component table, external services table, security section, Discovery Gaps.
- [ ] API contract source recorded: either `api/openapi-types.ts` generated from a reachable spec (technical) OR `.context/business/business-api-map.md` planned for after discovery (business). If neither is reachable, logged as a Discovery Gap with a concrete next step.
- [ ] `.context/SRS/functional-specs.md` exists with FR entries covering the top-5 critical flows, at least one state machine diagram, BR summary, Discovery Gaps.
- [ ] `.context/SRS/non-functional-specs.md` exists with all five NFR categories populated (even if several are "Not implemented — recommend adding"), Discovery Gaps.
- [ ] Every numerical claim (response time, cache TTL, rate limit) has an evidence path or appears under Discovery Gaps.
- [ ] No `.env` secrets, no hard-coded credentials, no AI-attribution lines in any file.
- [ ] User confirms "Phase 2 complete" before Phase 3 begins.

# Phase 3 — Infrastructure Discovery

> Read this when running any Phase 3 sub-step: Backend Discovery, Frontend Discovery, or Infrastructure Mapping. Phase 3 runs after Phase 2 is complete (Architecture + API contracts are the inputs).

---

## Phase 3 outputs

| File | Purpose |
|------|---------|
| `.context/infrastructure/backend.md` | Runtime, dependencies, env vars, DB setup, test/build commands, local-dev recipe. |
| `.context/infrastructure/frontend.md` | Build config, client env vars, static assets, bundle/perf, browser targets. |
| `.context/infrastructure/infrastructure.md` | CI/CD workflows, deployment targets, environment matrix, IaC, monitoring, rollback. |

Some teams merge backend + frontend sections into `.context/SRS/architecture.md`. Either layout is acceptable; pick one and be consistent. Prefer `.context/infrastructure/` when the target is a monorepo or has non-trivial ops surface.

Every output MUST include a `## Discovery Gaps` section.

---

## Stack detection — decision tree

Run this BEFORE any discovery step. Never ask the user "what stack is this?" — detect, then confirm.

### Backend signals

| Signal file | Stack inference |
|-------------|-----------------|
| `package.json` with `next` dep | Next.js (API routes in `src/app/api/` or `pages/api/`) |
| `package.json` with `express` or `fastify` | Node API server — look in `src/routes/` or `src/app.ts` |
| `package.json` with `@nestjs/core` | NestJS — controllers under `src/*/` with `@Controller()` decorator |
| `package.json` with `koa` | Koa — `src/app.js` + router middleware |
| `pyproject.toml` + `django` | Django — `urls.py` is the route map, views in `views.py` |
| `pyproject.toml` + `fastapi` | FastAPI — `@app.get/@app.post` decorators |
| `pyproject.toml` + `flask` | Flask — `@app.route` decorators |
| `composer.json` + `laravel/framework` | Laravel — `routes/*.php` |
| `Gemfile` + `rails` | Rails — `config/routes.rb` |
| `go.mod` + `gin`/`echo`/`fiber`/`chi` | Go web framework — grep handler registrations |
| `pom.xml` or `build.gradle` + Spring | Spring Boot — `@RestController` / `@RequestMapping` |

### Frontend signals

| Signal file | Stack inference |
|-------------|-----------------|
| `next.config.*` | Next.js SSR/SSG/ISR. Check `app/` vs `pages/` dir to detect router. |
| `vite.config.*` + `react` dep | Vite + React SPA (CSR) |
| `vite.config.*` + `vue` dep | Vite + Vue SPA |
| `nuxt.config.*` | Nuxt (Vue SSR/SSG) |
| `angular.json` | Angular — modules/components under `src/app/` |
| `svelte.config.*` | SvelteKit |
| `astro.config.*` | Astro — content-first, island architecture |
| `remix.config.*` or `vite.config` with `@remix-run` | Remix |
| No build config but `public/index.html` | Legacy CRA / custom webpack — check `package.json` scripts |

### Infrastructure signals

| Signal | Inference |
|--------|-----------|
| `.github/workflows/*.yml` | GitHub Actions |
| `.gitlab-ci.yml` | GitLab CI |
| `azure-pipelines.yml` | Azure DevOps |
| `.circleci/config.yml` | CircleCI |
| `Jenkinsfile` | Jenkins |
| `vercel.json` or `now.json` | Vercel |
| `netlify.toml` | Netlify |
| `Dockerfile` | Containerized — check for multi-stage |
| `docker-compose.yml` | Local multi-service dev — service list is authoritative |
| `k8s/` or `kubernetes/` or `helm/` | Kubernetes |
| `serverless.yml` / `serverless.ts` | Serverless Framework |
| `*.tf` files | Terraform |
| `Pulumi.yaml` | Pulumi |
| `cdk.json` | AWS CDK |
| `.do/app.yaml` | DigitalOcean App Platform |
| `render.yaml` | Render |
| `fly.toml` | Fly.io |

### Monorepo signals

`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, `rush.json`, root `package.json` with `workspaces` field.

If any of these are present: Phase 3 must be run ONCE PER PACKAGE. Each package gets its own sub-section inside the output files (`## packages/api`, `## packages/web`, ...).

---

## 1. Backend discovery

### Discovery process

1. **Runtime configuration**:
   - Language + version: `.nvmrc`, `.node-version`, `engines` in `package.json`, `.python-version`, `.ruby-version`, `go.mod`, `java` version in `pom.xml`.
   - Package manager: lock files decide (`package-lock.json` = npm, `yarn.lock` = yarn, `pnpm-lock.yaml` = pnpm, `bun.lockb` = bun).
   - Build tooling: `tsconfig.json` for TS; framework-specific config files.
   - Scripts: `cat package.json | jq .scripts` (or equivalent for the stack).

2. **Dependency analysis**:
   - Critical categories: framework, ORM (Prisma / TypeORM / Drizzle / Sequelize / SQLAlchemy), auth (NextAuth / Passport / jose / jsonwebtoken), validation (Zod / Yup / Pydantic / class-validator), HTTP client (axios / got / ky).
   - Note exact versions — downstream tests may pin against them.
   - Check for `peerDependencies` conflicts.

3. **Environment requirements**:
   - Start with `.env.example` / `.env.template`.
   - Cross-check against code: `grep -rh "process\.env\." src/ | sed 's/.*process\.env\.\([A-Z_]*\).*/\1/' | sort -u` (or `os.environ.get` / `ENV[]` for other langs).
   - Classify each var: Required (app won't start without it), Optional (has default), External Service (only needed when feature enabled), Build-time vs Runtime.
   - Credentials: see SKILL.md §Gotchas. Never paste actual values in these docs — document the KEY and example format only.

4. **Database setup**:
   - Provider from DATABASE_URL format (`postgres://`, `mysql://`, `mongodb://`).
   - Migration tool: `prisma/migrations/`, `migrations/` (TypeORM / Knex / Alembic), `db/migrate/` (Rails).
   - Seed mechanism: `prisma/seed.ts`, `db/seeds/`, custom scripts.
   - Connection pooling config and pool size.

5. **Test & build commands** — identify exactly what CI runs:
   - Test runner: jest, vitest, mocha, playwright, cypress, pytest, rspec, go test.
   - Build command + output dir.
   - Type check command (if separate from build).
   - Lint command.

### Required sections in `.context/infrastructure/backend.md`

- Runtime Environment table (runtime / version / language / package manager)
- Package Scripts table (name / command / purpose)
- Core Dependencies table (category / package / version / purpose)
- Environment Variables — three sub-tables (Required / Optional / External Service)
- Database Configuration (type / provider / ORM / migration tool)
- Migration Commands block (create / apply / reset / seed)
- Build Configuration (output dir, standalone flag, bundler settings)
- Local Development Setup — copy-pasteable `bash` block from `git clone` to `npm run dev`
- Health Check Endpoints (if implemented)
- Discovery Gaps

### Local dev recipe template

```bash
# 1. Install dependencies
<pkg-manager> install

# 2. Set up environment
cp .env.example .env.local
# Edit .env.local:
#   DATABASE_URL=<your local DB connection>
#   <other required vars>

# 3. Set up database
<migrate-command>
<seed-command>  # if seed exists

# 4. Start development server
<dev-command>

# 5. Verify
curl http://localhost:<port>/api/health
```

---

## 2. Frontend discovery

### Discovery process

1. **Build configuration**:
   - Framework config file (`next.config.*`, `vite.config.*`, `angular.json`, etc.).
   - Bundler: Webpack (default), Turbopack (Next 13+), Rollup (Vite), esbuild (various), SWC.
   - Output mode: SSR, SSG, ISR, SPA, standalone server.
   - TypeScript settings (strict mode, paths, jsx).
   - Custom webpack / plugin additions.

2. **Client env vars** — vars exposed to the browser:
   - Next.js: `NEXT_PUBLIC_*` prefix — `grep -rh "NEXT_PUBLIC_" --include="*.ts" --include="*.tsx" src/`.
   - Vite: `VITE_*` prefix — `grep -rh "import\.meta\.env\.VITE_" src/`.
   - CRA: `REACT_APP_*` prefix.
   - SECURITY CHECK: scan for any secret-looking names in the public prefix (e.g., `NEXT_PUBLIC_STRIPE_SECRET_KEY` is a red flag). Flag, don't fix — it's a security finding.
   - Document per-environment values (Development / Staging / Production).

3. **Static assets**:
   - Inventory `public/` contents (favicon, robots, sitemap, og images, fonts, locales).
   - Image optimization: `next/image` domains config, custom loader, formats (AVIF/WebP).
   - CDN: `assetPrefix`, CDN domain overrides.

4. **Bundle & performance**:
   - Bundle analyzer: `@next/bundle-analyzer`, `rollup-plugin-visualizer`, `webpack-bundle-analyzer`.
   - Code splitting signals: `dynamic(...)` (Next), `React.lazy`, `import(...)`.
   - Font optimization: `next/font`, `@fontsource/*`, self-hosted with preload.
   - Core Web Vitals measurement: `web-vitals` package, Lighthouse CI, Sentry Performance.

5. **Routing + state + auth integration points** — what the test framework needs to hook:
   - Router: Next App Router, Pages Router, React Router, Vue Router, Angular Router.
   - State: Redux, Zustand, Jotai, Recoil, Pinia, NgRx.
   - Data fetching: TanStack Query, SWR, Apollo, Relay, RTK Query, native fetch.
   - Auth client: NextAuth `useSession()`, Clerk, Auth0, Supabase Auth, custom cookie/JWT.
   - Test IDs strategy: `data-testid` (preferred), `data-cy`, id/class selectors.

### Required sections in `.context/infrastructure/frontend.md`

- Build Configuration table (framework / bundler / output mode / TS settings)
- Framework config snippet (key settings extracted from `next.config.*` / `vite.config.*`)
- Client Environment Variables table
- Environment-Specific Values table (dev / staging / prod)
- Static Assets tree + Image Handling table
- Code Splitting Strategy
- Bundle Size Notes (measured or flagged as gap)
- Performance Configuration table (image opt / font opt / prefetching / script opt)
- SEO Configuration (metadata / OG / sitemap / robots)
- Browser Support / Polyfills
- Routing + State + Auth integration points (consumed later by `/adapt-framework`)
- Discovery Gaps

---

## 3. Infrastructure mapping

### Discovery process

1. **CI/CD pipelines**:
   - Identify platform from signal files above.
   - Read ALL workflow files — typically a main `ci.yml` (lint/test/build) and a `deploy.yml`.
   - Extract triggers (`on:` block), jobs, steps, env vars, secrets referenced.
   - Note approval gates, branch protection references, reusable workflows.
   - Record the exact commands CI runs — tests must match those commands locally.

2. **Deployment targets**:
   - Primary platform from signal files (Vercel / Netlify / AWS / Fly / Render / k8s / bare Docker).
   - Deployment method: platform build, Docker image push, static upload, `kubectl apply`.
   - Regions and replica counts (if known).
   - Preview environments per PR (Vercel default, Netlify deploy previews, manual k8s).

3. **Environment matrix**:
   - List all environments (dev / preview / staging / prod / others).
   - Map environment -> branch -> auto-deploy yes/no -> URL -> database.
   - Secrets storage: platform env vars, Vault, AWS Secrets Manager, Doppler, 1Password CLI.
   - DO NOT read actual secret values; record the storage mechanism and rotation cadence if known.

4. **Infrastructure as code** (if any):
   - Tool (Terraform / Pulumi / CDK / Serverless / Ansible).
   - Location (`infra/`, `terraform/`, `cdk/`).
   - State backend (local vs remote — S3, Terraform Cloud, etc.).
   - Resource inventory: databases, buckets, queues, CDN distributions, DNS, secrets.

5. **Monitoring & rollback**:
   - Error tracking (Sentry, Rollbar, Bugsnag).
   - Uptime monitoring (UptimeRobot, Pingdom, BetterStack).
   - Metrics/APM (Datadog, New Relic, Grafana Cloud, CloudWatch).
   - Log shipping destination + retention.
   - Rollback mechanism: `vercel rollback`, `kubectl rollout undo`, redeploy prior Git SHA.

### Required sections in `.context/infrastructure/infrastructure.md`

- Overview diagram (Mermaid `graph TB` showing Dev -> CI -> Envs -> Infra)
- CI/CD Configuration — Platform + Workflows, per workflow (triggers, jobs, steps, env names)
- Deployment Configuration — Hosting platform, platform-specific config snippet, Docker/Compose summary if applicable
- Environments Matrix (env / URL / branch / auto-deploy)
- Environment Variables by Environment table
- Secrets Management table (secret / storage / access scope)
- Cloud Services table (service / provider / purpose)
- Database Infrastructure (provider / type / region / backups / connection)
- Infrastructure Resources diagram (Mermaid — apps, DBs, external services, CDN)
- IaC section (tool / location / state / resources)
- Monitoring & Observability (error tracking, uptime, logging)
- Deployment Checklist (pre-deploy / post-deploy / rollback)
- Discovery Gaps
- QA Relevance (test environment access, CI integration points for test jobs)

### Environment matrix template

```markdown
| Environment | URL | Branch | Auto Deploy | Approval |
|-------------|-----|--------|-------------|----------|
| Development | http://localhost:3000 | - | - | - |
| Preview | <pattern>.vercel.app | PR | Yes | - |
| Staging | <staging URL> | develop | Yes | - |
| Production | <prod URL> | main | <Yes/No> | <Manual/Automatic> |
```

---

## Stack detection gotchas

- **Monorepos hide their internals.** A top-level `package.json` with no deps of its own is a workspace root. Run detection per package.
- **Hybrid stacks are common.** Next.js + separate Express API, Next.js + tRPC, Rails API + React SPA. Treat the two halves as separate backend/frontend discoveries and link them in the infrastructure mapping diagram.
- **Missing Dockerfile is not a red flag.** Many modern deployments (Vercel, Netlify, Fly) build without a Dockerfile. Check for platform-specific config (`vercel.json`, `fly.toml`) before assuming "no deploy config".
- **Old `pages/` next to new `app/`.** Next.js apps mid-migration have both. Document both routing models — tests may need to target either.
- **Serverless edge runtime.** Next.js middleware and edge functions run in a restricted V8 runtime (no `fs`, limited `crypto`). Flag if tests assume Node APIs.
- **CI uses different commands than devs.** Read `.github/workflows/*.yml` for the authoritative command set. Local `package.json` scripts can drift.
- **Preview deployments have unstable URLs.** Don't hard-code preview URLs in tests; use the PR's deployment URL from the CI output.
- **Secrets in `.env.example`.** Some repos commit real secrets by mistake into `.env.example`. If you see values that look like tokens (long hex/base64), flag as a security finding rather than copying.
- **Database URL format lies about provider.** `postgres://` can point to Supabase, Neon, RDS, local Postgres. Check the host to identify the real provider.
- **Python projects split tools.** `pyproject.toml` (Poetry / Hatch / Rye) vs `requirements.txt` + `setup.py` — check both.
- **Turbopack vs Webpack in Next.js.** `next dev --turbo` behaves differently from Webpack for some plugins. Note which CI/local uses.

---

## Deliverables checklist

Before the Phase 3 completion gate, verify:

- [ ] `.context/infrastructure/backend.md` exists with Runtime, Scripts, Dependencies, Env Vars, Database, Local Dev Recipe, Discovery Gaps.
- [ ] `.context/infrastructure/frontend.md` exists with Build Config, Client Env Vars, Static Assets, Bundle/Perf, Routing/State/Auth integration points, Discovery Gaps.
- [ ] `.context/infrastructure/infrastructure.md` exists with CI/CD, Deployment, Environments, Secrets, IaC (or "Not present"), Monitoring, Rollback, Discovery Gaps.
- [ ] Every command block is copy-pasteable (no `<placeholder>` mixed with real commands).
- [ ] No secret values committed; only keys + example formats.
- [ ] Monorepos have per-package sub-sections.
- [ ] Each environment URL is reachable (or flagged as gap if cannot verify from code).
- [ ] User confirms "Phase 3 complete" before Phase 4 begins. KATA adaptation happens later via `/adapt-framework`, outside this skill.

# Phase 4 — Specification (Backlog Mapping + Access Recipe)

> Read this when running the Phase 4 sub-step: PBI Backlog Mapping. Phase 4 runs after Phase 3 is complete. Do NOT duplicate backlog content into the repo — document HOW to access it.

> **Per-ticket PBI is NOT a Phase-4 output.** It is materialized later by `/sprint-testing` via `bun run jira:sync-issues get <KEY> --include-comments`, which syncs Jira issues into the canonical tree `.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/` (Module = Epic, 1:1). Those local `.md` files are a READ-ONLY cache of Jira (Jira = source of truth). Phase 4 only produces the backlog access recipe (`ACCESS.md`) — it never authors `story.md` or any per-ticket file locally.

---

## Phase 4 outputs

| File | Purpose |
|------|---------|
| `.context/PBI/ACCESS.md` | PM tool, project key, backlog location + access methods, project structure, common queries, discovery gaps. |

Every output MUST include a `## Discovery Gaps` section if a field could not be verified (e.g., workflow states are assumed, no access to create-meta).

> **Hands off `.context/PBI/README.md` and `templates/`.** `README.md` is a `[COMMIT]` framework document holding the tier doctrine and gitignore ladder for the whole PBI tree — overwriting it destroys framework doctrine, so Phase 4 NEVER writes it. `templates/` (`PROGRESS-template.md`, `ROADMAP-template.md`, `module-context-template.md`) ships committed with the framework and is not authored per-project either. Phase 4's only write target is `ACCESS.md`, regenerated on every re-run of discovery.

---

## Golden rules

1. **Do NOT copy the backlog.** The issue tracker is the source of truth for tickets. `.context/PBI/` holds the backlog access recipe (`ACCESS.md`) plus the committed framework skeletons (`templates/`), never a copy of the full backlog. Per-ticket PBI is synced on demand from Jira by `/sprint-testing` (`bun run jira:sync-issues`) as a read-only cache.
2. **Per-ticket PBI is synced, not authored.** The canonical synced tree is `.context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/`, materialized by `/sprint-testing` from Jira. It is a read-only cache and can always be re-synced — this skill does not create it.
3. **Tracker credentials in `.env` only.** Two keys: `ATLASSIAN_EMAIL`, `ATLASSIAN_API_TOKEN` — consumed by MCP, acli, xray-cli, sync scripts, and the Jira-Direct TMS provider. The site HOST is NOT a credential and NOT in `.env`: it lives in `.agents/project.yaml` -> `issue_tracker.atlassian_url` (read it with `bun run --silent jira:url`). No `JIRA_*` credential aliases exist; if you see them in old docs or `.env` files, migrate them. Never paste tokens in markdown; if the user pastes one in chat, scrub it and redirect them to `.env`. See SKILL.md §Gotchas for the general credential policy.
4. **Tool resolution.** When you see `[ISSUE_TRACKER_TOOL]` in this document, resolve via the project's AGENTS.md Tool Resolution table. Priority order: CLI (fewer tokens) -> MCP (fallback) -> REST API -> manual. For Jira, that means load `/acli` skill first; only fall back to Atlassian MCP if acli is unavailable.

---

## Step 1 — PM Tool Identification

### Detection

| Source | What to look for |
|--------|------------------|
| `.context/project-config.md` | Existing `jira` / `azure-devops` / `clickup` / `linear` / `asana` mention |
| `package.json`, `.github/workflows/**` | Integrations, webhooks, bot tokens |
| Commit footers, PR templates | `PROJ-123` style refs -> Jira; `#123` -> GitHub; `AB#123` -> Azure Boards |
| `.gitlab-ci.yml` / `.circleci/config.yml` | Tracker hooks |

If nothing is detectable, ask once:

```
What tool manages your backlog? (Jira Cloud, Jira DC, Azure DevOps, Linear, ClickUp, GitHub Issues)
What is the project key or board name?
```

### Output of this step

- PM tool name + instance URL
- Project key / board name
- Whether the team uses sprints (Scrum), continuous flow (Kanban), or hybrid

> **Tooling coverage by tracker**: Jira uses `/acli` (primary skill); GitHub Issues uses `gh issue` CLI. Azure DevOps / Linear / ClickUp have no dedicated skill in this ecosystem — fall back to MCP (if available) or document REST API + token in `.context/PBI/ACCESS.md`. Flag the absence of a proprietary skill as a Discovery Gap so future adopters know what's unsupported.

---

## Step 2 — Project Structure Mapping

> **Prerequisite**: Load `/acli` skill before executing the commands below.

### Jira

```
[ISSUE_TRACKER_TOOL] List Projects:
  filter: {{PROJECT_KEY}}

[ISSUE_TRACKER_TOOL] List Boards:
  project: {{PROJECT_KEY}}

[ISSUE_TRACKER_TOOL] Get Create Meta:
  project: {{PROJECT_KEY}}
```

### Azure DevOps

```
[ISSUE_TRACKER_TOOL] List Projects
[ISSUE_TRACKER_TOOL] List Iterations:
  project: {{PROJECT_KEY}}
[ISSUE_TRACKER_TOOL] List Work Item Types:
  project: {{PROJECT_KEY}}
```

### Capture

- Issue types in use (Epic / Story / Task / Bug / Sub-task / custom)
- Workflow states and transitions (paste into a Mermaid state diagram)
- Sprint cadence (length, current sprint, next sprint)
- Required custom fields (if any)

If tool access is unavailable, ask the user for project key + board type and flag the rest as a Discovery Gap.

---

## Step 3 — Access Method Priority

| Rank | Method | When it fits |
|------|--------|--------------|
| 1 | MCP (e.g., Atlassian MCP) | Preferred — rich integration, live queries, schema-aware |
| 2 | CLI (e.g., `acli` for Jira, `gh issue` for GitHub, `az boards` for Azure DevOps) | Scriptable, no MCP available |
| 3 | REST API + token | Fallback, document `curl` recipe |
| 4 | Manual (Web UI) | Last resort; note in Discovery Gaps |

Record the chosen method and fallback in `.context/PBI/ACCESS.md`.

### Required env keys (emit to user)

```
# Atlassian credentials (no JIRA_* aliases)
# NOTE: the Atlassian site HOST is not a .env variable. It lives in
# .agents/project.yaml -> issue_tracker.atlassian_url (`bun run agents:setup`).
ATLASSIAN_EMAIL=
ATLASSIAN_API_TOKEN=
```

---

## Step 4 — Query Patterns

Document the four canonical QA queries. Resolve to the tracker's query language.

| Need | Jira JQL | Azure DevOps WIQL |
|------|----------|-------------------|
| Current sprint ready for QA | `project = {{PROJECT_KEY}} AND sprint in openSprints() AND status = "{{jira.status.story.ready_for_qa}}"` | `State = 'Ready for Test' AND [System.IterationPath] = @CurrentIteration` |
| All open bugs | `project = {{PROJECT_KEY}} AND type = Bug AND resolution = Unresolved ORDER BY priority DESC` | `Work Item Type = 'Bug' AND State <> 'Closed'` |
| My testing tasks | `project = {{PROJECT_KEY}} AND status = "{{jira.status.story.in_test}}" AND assignee = currentUser()` | `State = 'Testing' AND [System.AssignedTo] = @Me` |
| Recently updated | `project = {{PROJECT_KEY}} AND updated >= -1d ORDER BY updated DESC` | `[Changed Date] > @Today - 1` |

Also record the `[ISSUE_TRACKER_TOOL]` pseudocode equivalents so other skills can reuse them.

---

## `.context/PBI/ACCESS.md` structure

Produce with these sections, in order:

1. **Header** — PM tool, project key, board, access method, last updated.
2. **Backlog Location** — URL, project key, board name + type.
3. **Access Configuration** — primary method (MCP/CLI/API), setup steps, fallback method, required env vars.
4. **Project Structure** — issue types table, workflow state diagram (Mermaid), sprint cadence.
5. **Common Queries** — the four canonical queries above, plus any project-specific ones.
6. **Integration with KATA** — when to fetch (during sprint-testing, bug triage, documentation, automation handoff), local storage rules.
7. **Credentials** — which env vars must be set; never paste secrets (see SKILL.md §Gotchas).
8. **Discovery Gaps** — anything not verifiable from code or tracker access.

### Local storage layout

```
.context/PBI/
|-- README.md                 # [COMMIT] framework-owned — tier doctrine + gitignore ladder; Phase 4 NEVER writes it
|-- ACCESS.md                 # Phase 4 output — backlog access recipe + common queries
|-- templates/                # [COMMIT] framework skeletons — shipped with the repo, NOT Phase-4 outputs
|   |-- PROGRESS-template.md
|   |-- ROADMAP-template.md
|   `-- module-context-template.md
`-- epics/                    # synced from Jira by /sprint-testing — read-only cache, NOT created here
    `-- EPIC-{{PROJECT_KEY}}-100-<slug>/
        `-- stories/
            `-- STORY-{{PROJECT_KEY}}-123-<slug>/
                `-- ...        # materialized by `bun run jira:sync-issues get <KEY> --include-comments`
```

> Phase 4 produces ONLY `ACCESS.md`. The `epics/.../stories/...` tree is synced from Jira on demand by `/sprint-testing` (Module = Epic, 1:1) and is a read-only cache of Jira — this skill never writes it.


## Gotchas

- **Undocumented tickets.** Teams frequently open stories with "TBD" ACs or empty descriptions. When mapping, record the prevalence ("~30% of recent stories lack ACs") as a Discovery Gap — this becomes the shift-left opportunity for the QA role.
- **Missing ACs.** Do NOT invent ACs. ACs live in Jira (source of truth); if recent tickets frequently lack them, record the prevalence as a Discovery Gap (the shift-left opportunity) rather than back-filling. Per-ticket emptiness is surfaced later by `/sprint-testing` from the synced Jira cache, not authored here.
- **Orphaned stories.** Stories with no Epic, or Epics with no parent theme, are common. Document the orphan count but do not attempt to re-parent from the skill.
- **Custom workflow states.** Every team renames states (`Ready for QA` vs `In QA` vs `Testing`). Capture the real state names in the workflow diagram; do not force a generic template.
- **Workflow drift.** The create-meta endpoint may list states that the current board does not actually use. When in doubt, read recent tickets to see which states appear in practice.
- **Permission gaps.** The QA user may not have permission to transition tickets. Test a state transition manually before committing a workflow diagram to `ACCESS.md`.
- **Sprint naming inconsistency.** Sprints named `Sprint 42`, `S42`, `2026-W15`, `Hawking` all coexist in mature teams. Record the naming convention in use, do not normalize it.
- **Required custom fields.** `Story Points`, `Epic Link`, `Acceptance Criteria` (as a field, not description), `Components`. Fetch these from create-meta and record them in `ACCESS.md` §Project Structure; missing required fields will block ticket creation from CLI.
- **Two states named "Done".** Jira commonly has both `Done` and `Closed`; some workflows have `Resolved` in between. Capture all terminal states.
- **Do not hardcode issue types.** A project may not use `Sub-task`; another may have `Spike`, `Chore`, or `Incident`. Enumerate what the project actually uses.
- **Do not embed secrets in examples.** CLI invocations must use env-var interpolation (`$ATLASSIAN_API_TOKEN`), not literal tokens.

---

## When to re-run Phase 4

| Trigger | Action |
|---------|--------|
| New PM tool adopted | Re-run Step 1-3; rewrite `.context/PBI/ACCESS.md`. |
| Workflow states changed | Re-run Step 2; update state diagram only. |
| New required custom fields | Update the required-fields list in `ACCESS.md` §Project Structure. |
| Team switches Scrum <-> Kanban | Update Project Structure section and queries. |
| Tracker URL migration (e.g., Jira Cloud move) | Update env keys and setup instructions. |

---

## Completion checklist

Before reporting Phase 4 complete:

- [ ] `.context/PBI/ACCESS.md` exists with project key + access recipe + four common queries.
- [ ] `.context/PBI/README.md` and `.context/PBI/templates/` were NOT touched (framework-owned, committed).
- [ ] All outputs include a `## Discovery Gaps` section (can be empty, but must be present).
- [ ] No credentials pasted in markdown; env-var references only.
- [ ] Per-ticket PBI sync is documented as out of scope (synced from Jira by `/sprint-testing`, not created here).
- [ ] User has confirmed the workflow diagram matches reality (manual transition test or recent ticket review).

Emit the phase completion ping and wait for user confirmation before moving to the context generators. KATA adaptation is out of scope for this skill — it is owned by the `/adapt-framework` command and runs after discovery outputs exist.