# Pbi Challenge > [Code Quality] Use when you need an AI-assisted Dev BA PIC review of PBI drafts. - Skill: `duc01226/pbi-challenge` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/pbi-challenge` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/pbi-challenge/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/pbi-challenge --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends. > **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason. > **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions. ## Quick Summary **Goal:** Break drafter confirmation bias before grooming — by helping **Dev BA PIC** (Person In Charge — development Business Analyst responsible for technical review sign-off per squad) review BA drafters' PBI drafts with specific, actionable challenge prompts, surface every architectural-feasibility, vague-AC, missing-auth, cross-service, and M1-M7 gap so an INFEASIBLE or under-specified PBI never reaches grooming with a false APPROVE. AI provides analysis; human makes decision. **Summary:** - **Main steps (8):** (1) locate the BA drafter's PBI draft → (2) auto-detect module, **confirm by asking the user directly BEFORE loading domain docs** (domain-entities-reference + `docs/specs/{App}/` + BR-{MOD} rules) → (3) Technical Feasibility analysis (architecture fit, entity conflicts, cross-service, complexity vs SP) → (4) AC Quality analysis (vagueness detector + M1-M7 checks) → (5) Cross-Cutting Concerns (auth matrix, seed data, migration, performance, UI Layout) → (6) generate SPECIFIC challenge prompts with suggested answers → (7) present Challenge Prompts FIRST, THEN AI Verdict (APPROVE / REQUEST_REVISION / ESCALATE_TO_LEAD) → (8) human records final decision by asking the user directly. - CROSS-PERSON review, NOT self-review: a _different_ reviewer (Dev BA PIC) challenges the BA drafter's PBI — NEVER your own draft (route self-review to `$artifact-review --type=pbi`). — why: external skepticism breaks blind spots that self-review rationalizes away. - M1-M7 Compliance Gate is BLOCKING and drives the verdict (runs inside Steps 4-5): any M1-M5 or M7 mandate failure forces REQUEST_REVISION with a challenge prompt naming the violated mandate ID + exact section/line/AC; an APPROVE over an M1-M5 or M7 violation is itself defective. - Order fights automation bias: Challenge Prompts FIRST so the Dev BA PIC forms their own view, THEN the AI Verdict; challenges must be SPECIFIC with suggested answers, never vague. - AI provides ANALYSIS; the human makes the DECISION by asking the user directly — never auto-approve or auto-reject. **Key distinction:** Collaborative review tool (drafter → reviewer flow), NOT self-review (use `$artifact-review --type=pbi` for AI self-review). **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** ## Why This Skill Exists PBI drafts routinely pass informal review unchallenged on architectural feasibility, vague AC, missing auth scenarios, cross-service impact. `$refine` generates PBIs but does not adversarially challenge them — creation tool, not review tool. `$artifact-review --type=pbi` provides AI self-review for drafter, but drafter has inherent blind spots about own assumptions. Separate reviewer (Dev BA PIC) applying AI-assisted challenge prompts breaks drafter confirmation bias before grooming — catches gaps drafter cannot catch themselves. **Why not just `$artifact-review --type=pbi`?** Drafter runs it on own work; even with adversarial prompts, drafter rationalizes own choices. `pbi-challenge` invoked by different person with different mandate — external skepticism requires different author, not different tool on same author. ## Alternatives Considered | Approach | Pros | Cons | Decision | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Extend `$artifact-review --type=pbi` with a reviewer-role flag | No new skill, single codebase | Drafter runs it themselves in practice; role separation breaks down without enforcement | Rejected — role separation requires a distinct invocation point owned by a different person | | Fully autonomous AI verdict (no human decision) | Faster, no Dev BA PIC scheduling needed | Automation bias: AI wrong on domain specifics propagates unchecked; no human accountability for false APPROVE | Rejected — cost of false APPROVE on infeasible PBIs exceeds review time saved | | Static DoR checklist given to Dev BA PIC (no AI) | Simple, no AI dependency | No domain entity context loading, no AC vagueness flagging; manual effort is high and inconsistent across reviewers | Rejected — AI domain lookup provides non-trivial value for cross-service entity detection | | Async comment-thread model (AI generates questions posted as ticket comments) | Eliminates scheduling bottleneck; drafter can research before responding | Slower feedback loop; requires external ticket integration | Valid alternative for async teams; prefer if Dev BA PIC availability is chronically a bottleneck | ## Risk Assessment | Risk | Likelihood | Impact | Mitigation | | -------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | **Automation bias** — Dev BA PIC rubber-stamps AI verdict without independent assessment | High | High | Workflow Step 7 shows challenge prompts BEFORE the verdict — Dev BA PIC forms their own view first | | **Module misdetection** — AI loads wrong domain context, produces entity conflict analysis for wrong service | Medium | High | Workflow Step 2 confirms detected module with Dev BA PIC by asking the user directly before proceeding | | **Challenge prompts ignored** — Drafter revises PBI superficially to satisfy reviewer without resolving root gaps | Medium | Medium | Decision Record includes drafter-response field; Dev BA PIC re-runs skill on revision, not just reads revised PBI | | **Suggested answers create adoption pressure** — Drafter adopts suggested answer rather than reasoning independently | Medium | Medium | Suggested answers framed as "consider whether X" options, not corrections; language review in challenge prompt templates | | **3-way BA vote deadlock** — UX BA, Designer BA, Dev BA PIC all disagree | Low | Medium | Escalation path per `ba-team-decision-model`: Engineering Manager for tech uncertainty, PO for business value | ### Frontend/UI Context (if applicable) > When this task involves frontend or UI changes, - Component patterns: `docs/project-reference/frontend-patterns-reference.md` - Styling/BEM guide: `docs/project-reference/scss-styling-guide.md` - Design system tokens: `docs/project-reference/design-system/README.md` ## Workflow 1. **Locate PBI draft** — Find BA drafters' draft PBI in `team-artifacts/pbis/` or path provided by user 2. **Load domain context** — Auto-detect module from PBI content. **MANDATORY: Use ask the user directly to confirm detected module with Dev BA PIC before loading domain docs.** Wrong module = wrong entity context = false APPROVE risk. Then load: - `docs/project-reference/domain-entities-reference.md` (entity definitions) - Relevant feature docs from `docs/specs/{App}/` - Existing business rules (BR-{MOD}-XXX) from feature docs 3. **Technical Feasibility Analysis:** - Can described features be built with the project's architecture? - Any domain entity conflicts? (cross-reference entity definitions) - Any cross-service implications? (message bus events, shared data between services) - Estimated complexity alignment (does scope match story points?) 4. **AC Quality Analysis:** - Vagueness detector: flag "should", "might", "TBD", "etc.", "various", "appropriate" - Coverage check: happy path + edge case + error case + authorization scenario - Missing scenarios: suggest specific additions based on feature type 5. **Cross-Cutting Concerns Check:** - Authorization section present and complete? (roles × CRUD matrix) - Seed data requirements addressed? (or explicit "N/A") - Data migration implications? (schema changes) - Performance considerations? (list/grid/export features) - **UI Layout section present?** If PBI involves UI: must have `## UI Layout` per UI wireframe protocol with wireframe + components (with tiers) + states + design tokens. If backend-only: explicit "N/A". Flag missing UI visualization as a gap. 6. **Generate Challenge Prompts** — Output specific, actionable questions: - NOT vague: "needs work" or "improve AC" - SPECIFIC: "AC #2 says 'user can filter results' — which filters exactly? Suggest: status, date range, priority" 7. **Present Challenge Prompts first, then AI Verdict** — Output challenge prompts BEFORE the verdict to prevent automation bias. Dev BA PIC reads and forms their preliminary view, THEN sees: APPROVE / REQUEST_REVISION / ESCALATE_TO_LEAD - **Technical decisions** (feasibility, dependencies, cross-service impact, security): Dev BA PIC has unilateral veto power — no 2/3 vote needed - **Non-technical decisions** (UI/UX design, visual design, business value): 2/3 majority vote required (Dev BA PIC + UX BA + Designer BA per `ba-team-decision-model`) 8. **ask the user directly** — Dev BA PIC records their FINAL decision (APPROVE / REQUEST_REVISION / ESCALATE_TO_LEAD) in the Decision Record. This is the human decision step — NOT the workflow routing step (handled separately in Next Steps) ## M1-M7 Compliance Gate (BLOCKING — drives the AI Verdict) > **Contract:** See `.claude/skills/shared/sdd-artifact-contract.md` → "AI-SDD Mandates (M1-M7)". This challenge enforces M6: a PBI draft that violates any of M1-M5 or M7 MUST produce an AI Verdict of REQUEST_REVISION with a challenge prompt that names the violated mandate ID and cites the exact PBI section + line/AC. An APPROVE over an M1-M5 or M7 violation is itself defective. (AI provides the analysis; the human still records the final decision.) > > **M1 governs vocabulary; M7 governs subject matter.** A technical case written in impeccably tech-free prose satisfies M1 while violating M7 — that gap is the most common way business specs rot. A clean M1 pass is NEVER evidence of an M7 pass; challenge both. > > Carriers are EXEMPT from M1/M2 — source identifiers are CORRECT inside `[Source: ...]`, `**Evidence**`, `CoveredBy:` fields, legacy `**IntegrationTest:**` migration fields, YAML frontmatter, and ` ```mermaid ``` ` blocks. Only challenge leakage in PBI narrative prose (problem statement, AC text, scope, rule descriptions). Banned prose token list: `docs/project-reference/spec-principles.md` §3.2. Run these six checks as part of Step 4 (AC Quality) and Step 5 (Cross-Cutting Concerns); any failure becomes a specific challenge prompt and forces REQUEST_REVISION: - **MUST ATTENTION M1 — Tech-agnostic prose.** FAIL if problem statement, AC, or rule prose names framework/product, language-native type, or product/design-pattern class name (banned list `spec-principles.md` §3.2). Challenge: cite section + leaked token + business-term replacement. — why: stack-named prose locks the PBI to one implementation. - **MUST ATTENTION M2 — No source code in prose.** FAIL if requirement expressed as class/method/file-path/namespace instead of business operation. Source identifiers belong only in evidence carriers. Challenge: cite section + line. - **MUST ATTENTION M3 — Abstract-IDs-first.** FAIL if requirement/rule lacks logical ID (`FR-/BR-/OP-`), has logical ID but no `[Source: namespace/service/id]` abstract-anchor evidence, uses physical code coordinates or repository-root paths instead of abstract anchor, or makes anchor its primary citation. Evidence REQUIRED and KEPT, but SECONDARY to logical ID (physical coordinates live only in provenance sidecar). - **MUST ATTENTION M4 — Unambiguous AC.** FAIL if any AC uses vague language ("should", "might", "appropriate", "various", "as needed"), two engineers could implement it differently while both claiming conformance, or no observable completion state / named error condition exists. (Extends Step-4 vagueness detector to M4 verdict.) - **MUST ATTENTION M5 — Implementable from artifact alone.** FAIL if competent team with ZERO codebase knowledge could not build PBI on different stack from PBI alone (relies on reading source to understand it). Challenge: cite section + missing detail. - **MUST ATTENTION M7 — Business-visibility.** Apply the demo test to each case's BODY: _"what would a stakeholder SEE change?"_ — no answer → FAIL as TECHNICAL-ONLY and force REQUEST_REVISION. Every `Given` = a state a user could arrange; every `When` = an action a user could take; every `Then` = an outcome a user could see. FAIL a `When` that is an invocation (a handler runs, a consumer receives, a job fires, data syncs) or a `Then` asserting schema/type/nullability/call-count. Judge the BODY, never the title or ID. Challenge: cite section + the offending `Given`/`When`/`Then` + a demoable rewrite to consider. — why: a technical case in business clothing ships an un-demoable AC to grooming. If ANY check fails → AI Verdict is REQUEST_REVISION; tag each violated mandate ID with its concrete section/line citation in the Challenge Prompts and the AI Verdict Reason. ## Output ```markdown ## PBI Challenge Review **PBI:** {PBI filename} **Reviewer:** Dev BA PIC **Date:** {date} **Module:** {detected module code} ### Technical Feasibility **Status:** FEASIBLE | CONCERNS | INFEASIBLE {Analysis with evidence — cite domain entities, service boundaries, architecture constraints} ### AC Quality **Status:** GOOD | NEEDS_REVISION | POOR | AC # | Issue | Suggested Fix | | ---- | ---------------- | ------------------------- | | {#} | {specific issue} | {specific fix suggestion} | ### Cross-Cutting Concerns | Concern | Status | Issue | | -------------- | --------- | -------- | | Authorization | ✅/❌ | {detail} | | Seed Data | ✅/❌/N/A | {detail} | | Data Migration | ✅/❌/N/A | {detail} | | Performance | ✅/❌/N/A | {detail} | ### Challenge Prompts for BA Drafters 1. {Specific actionable question with suggested answer} 2. {Specific actionable question with suggested answer} 3. {Specific actionable question with suggested answer} ### AI Verdict **{APPROVE | REQUEST_REVISION | ESCALATE_TO_LEAD}** **Reason:** {evidence-based justification} **Confidence:** {X%} — {what was verified vs. what needs more investigation} ### Decision Record **Dev BA PIC Decision:** {filled after human review by asking the user directly} **Vote:** {approve / request-revision / escalate} **Conditions:** {if any} **Drafter Response (on revision):** {drafter's response to each challenge prompt — filled when Dev BA PIC re-runs on revised PBI} **Resolution:** {how each challenge prompt was addressed, deferred, or accepted as known risk} **Stored at:** `plans/reports/pbi-challenge-{YYMMDD}-{pbi-id}.md` (save output there for audit trail) ``` ## Key Rules - **AI provides ANALYSIS, human makes DECISION** — Never auto-approve or auto-reject - **Challenge prompts must be specific** — Include suggested answers, not just questions - **Domain context required** — Always load entity reference + feature docs before analysis - **Technical veto scope** — Dev BA PIC CAN veto: architecture feasibility, dependency correctness, cross-service impact, performance, security. CANNOT veto: UI/UX design, visual design, business value (see `ba-team-decision-model-protocol.md` §2) - **Evidence-based** — Every concern raised must cite source (protocol section, entity definition, feature doc) - **Constructive tone** — Focus on improving the PBI, not criticizing the drafters --- ## Next Steps **MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS** after completing this skill, you MUST ATTENTION use ask the user directly to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides: - **"$dor-gate (Recommended)"** — If APPROVE: validate DoR before grooming - **"$refine"** — If REQUEST_REVISION: BA drafters revise, then re-run `$pbi-challenge` - **"Escalate to Engineering Manager"** — If ESCALATE_TO_LEAD: document concern for technical consultation - **"Skip, continue manually"** — user decides > **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting. > **Evidence Gate:** MANDATORY IMPORTANT MUST ATTENTION — every claim requires `file:line` proof or traced evidence with confidence percentage (>80% to act). > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **UI System Context** — For ANY task touching `.ts`, `.html`, `.scss`, or `.css` files: > > **MUST ATTENTION READ before implementing:** > > 1. `docs/project-reference/frontend-patterns-reference.md` — component base classes, stores, forms > 2. `docs/project-reference/scss-styling-guide.md` — BEM methodology, SCSS variables, mixins, responsive > 3. `docs/project-reference/design-system/README.md` — design tokens, component inventory, icons > > Reference `docs/project-config.json` for project-specific paths. > **BA Team Decision Model** — 2/3 majority vote: Dev BA PIC + UX BA + Designer BA per squad. 2 of 3 agree = decision final. 3-way split = escalate to full squad + Tech Leads + Engineering Manager. > > **Technical Veto:** Dev BA PIC can unilaterally veto on: architecture feasibility, dependency correctness, cross-service impact, performance, security. CANNOT veto: UI/UX design, visual design, business value, user research. > > **Rules:** Disagree-and-commit after vote. Grooming override requires >75% non-BA squad vote. Record decisions in PBI Validation Summary (member, role, vote, notes). > > **Escalation:** Tech uncertainty → Engineering Manager. Business value → PO. Design feasibility → UX BA + Designer BA consensus. > **Refinement DoR Checklist** — ALL 7 criteria MUST ATTENTION pass before grooming: > > 1. **User story template** — "As a {role}, I want {goal}, so that {benefit}" format > 2. **AC testable & unambiguous** — GIVEN/WHEN/THEN. No "should/might/TBD/various/appropriate". Min 3 scenarios (happy, edge, error) + 1 auth scenario > 3. **Wireframes attached** — UI features: `## UI Layout` with wireframe + components + states + tokens. Backend-only: explicit "N/A" > 4. **UI design ready** — Visual design + component decomposition tree + design-spec linked (`$design-spec` artifact or inline UI specs in `## UI Layout`) for any PBI with UI work. Backend-only: "N/A" > 5. **AI pre-review passed** — `$artifact-review --type=pbi` or `$pbi-challenge` returned PASS or WARN (not FAIL) > 6. **Story points estimated** — Fibonacci 1-21 + complexity (Low/Medium/High). >13 SP → recommend split > 7. **Dependencies table complete** — Dependency, Type (must-before/can-parallel/blocked-by/independent), Status > > **Failure fixes:** Vague AC → specify exact CRUD + roles. Missing auth → add roles × CRUD table. No wireframes → UX BA creates. TBD in AC → replace with decision. > **Estimation Framework** — Bottom-up first; SP DERIVED; output min-max range when likely ≥3d. Stack-agnostic. Baseline: 3-5yr dev, 6 productive hrs/day. AI estimate assumes Claude Code + project context. > > **Method:** > > 1. **Blast Radius pass** (below) — drives code AND test cost > 2. Decompose phases → hours/phase → `bottom_up_hours = Σ phase_hours` > 3. `likely_days = ceil(bottom_up_hours / 6) × productivity_factor` > 4. Sum **Risk Margin** (base + add-ons) → `max_days = likely_days × (1 + margin)` > 5. `min_days = likely_days × 0.9` > 6. Output as range when `likely_days ≥3`; single point allowed `<3` (still record margin) > 7. `man_days_ai` = same range × AI speedup > 8. `story_points` DERIVED from `likely_days` via SP-Days — NEVER driver. Disagreement >50% → trust bottom-up > > **Productivity factor:** 0.8 strong scaffolding+codegen+AI hooks · 1.0 mature default · 1.2 weak patterns · 1.5 greenfield > > **Cost Driver Heuristic (apply BEFORE work-type row):** > > - **UI dominates** in CRUD/business apps — 1.5-3x backend (states, validation, responsive, a11y, polish) > - **Backend dominates ONLY:** multi-aggregate invariants, cross-service contracts, schema migrations, heavy query/perf, new event flows > > **Reuse-vs-Create axis (PRIMARY lever, per layer):** > > | UI tier | Cost | > | -------------------------------------------- | -------- | > | Reuse component on existing screen | 0.1-0.3d | > | Add control/column to existing screen | 0.3-0.8d | > | Compose components into NEW screen | 1-2d | > | NEW screen, custom layout/states/validation | 2-4d | > | NEW shared/common component (themed, tested) | 3-6d+ | > > | Backend tier | Cost | > | ---------------------------------------------------- | --------- | > | Reuse query/handler from new place | 0.1-0.3d | > | Small update existing handler/entity | 0.3-0.8d | > | NEW query on existing repo/model | 0.5-1d | > | NEW command/handler on existing aggregate (additive) | 1-2d | > | NEW aggregate/entity (repo, validation, events) | 2-4d | > | NEW cross-service contract OR schema migration | 2-4d each | > | Multi-aggregate invariant / heavy domain rule | 3-5d | > > **Rule:** Sum tiers across UI+backend+tests, apply productivity factor. Reuse short-circuits tiers — call out. > > **Test-Scope drivers (compute test_count EXPLICITLY — "+tests" hand-wave is #1 failure):** > > | Driver | Count | > | --------------------------------- | ------------------------------------------------------ | > | Happy-path journeys | 1 per story / AC main flow | > | State-machine transitions | reachable transitions × allowed actors | > | Multi-entity state combos | state(A) × state(B) — REACHABLE only, not Cartesian | > | Authorization matrix | (owner, non-owner, elevated, unauth) × each mutation | > | Validation rules | 1 per required field / boundary / format / cross-field | > | UI states (per new screen/dialog) | happy, loading, empty, error, partial — present only | > | Negative paths / invariants | 1 per violatable business rule | > > | Test tier (Trad, incl. setup+assert+flake) | Cost | > | ------------------------------------------ | -------- | > | 1-5 cases, fixtures reused | 0.3-0.5d | > | 6-12 cases, 1 new fixture | 0.5-1d | > | 13-25 cases, multi-entity setup | 1-2d | > | 26-50 cases OR new state-machine coverage | 2-3d | > | >50 cases OR full E2E journey | 3-5d | > > **Test multipliers:** new fixture/seed harness +0.5d · cross-service/bus assertion +0.3d each · UI E2E ×1.5 · each new role +1-2 cases > > **Blast Radius (mandatory pre-pass — affects code AND test):** > > 1. Files/components directly modified — count > 2. Of those, "complex" (>500 LOC, multi-handler, central, frequently-modified) — count > 3. Downstream consumers (callers, event subscribers, cross-service) — list > 4. Shared/common code touched (multi-app blast) — yes/no > 5. Regression scope — areas needing re-test > > **Rule:** Complex touch → add `risk_factors`. Each downstream consumer → +1-3 regression cases. Blast >5 areas OR >2 complex → re-evaluate SPLIT before estimating. > > **Risk Margin (drives max bound):** > > | likely_days | Base margin | > | ------------------- | ------------------------------- | > | <1d trivial | +10% | > | 1-2d small additive | +20% | > | 3-4d real feature | +35% | > | 5-7d large | +50% | > | 8-10d very large | +75% | > | >10d | +100% AND **flag SHOULD SPLIT** | > > **Risk-factor add-ons (additive — enumerate in `risk_factors`):** > > | Factor | +margin | > | --------------------------------------------------------------------- | ------- | > | `touches-complex-existing-feature` (>500 LOC, multi-handler, central) | +20% | > | `cross-service-contract` change | +25% | > | `schema-migration-on-populated-data` | +25% | > | `new-tech-or-unfamiliar-pattern` | +30% | > | `regression-fan-out` (≥3 downstream areas re-test) | +20% | > | `performance-or-latency-critical` | +20% | > | `concurrency-race-event-ordering` | +25% | > | `shared-common-code` (multi-consumer/multi-app) | +25% | > | `unclear-requirements-or-design` | +30% | > > **Collapse rule:** total margin >100% → STOP, split (padding past 2x is dishonesty). Margin <15% on `likely_days ≥5` → under-estimated, widen. > > **Work-Type Caps (hard ceilings on `likely_days`):** > | Work type | Max SP | Max likely | > | --- | --- | --- | > | Single field / config flag / style fix | 1 | 0.5d | > | Add property to existing model + bind to existing UI | 2 | 1d | > | **Additive endpoint + minor UI control** (button/menu/column), reuses fixtures | **3** | **2-3d** | > | Additive endpoint + **NEW UI surface** OR additive multi-layer + new domain rule + 2+ test files | 5 | 3-5d | > | NEW model/aggregate OR migration OR cross-module contract OR heavy test (>1.5d) OR NEW UI + non-trivial backend | 8 | 5-7d | > | NEW UI surface + (NEW aggregate OR migration OR cross-service contract) | 13 | SHOULD split | > | Cross-service contract + migration combined | 13 | SHOULD split | > | Beyond | 21 | MUST split | > > **SP→Days (validation only):** 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d (Trad/AI likely) > **AI speedup:** SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x. AI cost = `(code_gen × 1.3) + (test_gen × 1.3)` (30% review overhead). > > **MANDATORY frontmatter:** > > ```yaml > story_points: > complexity: low | medium | high | critical > man_days_traditional: '-d' # range when likely ≥3d; 'd' when <3d > man_days_ai: '-d' > risk_margin_pct: # base + add-ons > risk_factors: [touches-complex-existing-feature, regression-fan-out] # closed-list from add-ons; [] if none > blast_radius: > touched_areas: > complex_touched: > downstream_consumers: [list or count] > shared_common_code: yes | no > estimate_scope_included: [code, integration-tests, frontend, i18n, docs] > estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds] > estimate_reasoning: | > 5-7 lines covering: > (a) UI tier — row applied > (b) Backend tier — row applied > (c) Test scope — case breakdown by driver, file count, fixtures, tier row > (d) Cost driver — dominant tier + why > (e) Blast radius — touched, complex, regression scope > (f) Risk factors — list driving margin; why not larger/smaller > Example: "UI: compose Form/Table/Dialog → NEW screen (~1.5d). Backend: NEW command on existing aggregate, > reuses validation+repo (~1d). Tests: 4 transitions × 2 actors + 3 validation + 2 UI states = 13 cases, > 1 new fixture → tier 13-25 ~1.5d. Driver: UI composition + new states. Blast: 4 areas, 1 complex. > Risk: base 35% + touches-complex +20% = 55% → max 3.9d → range 2.5-4d." > ``` > > **Sanity self-check:** > > - `likely_days ≥3d` and single-point? → reject, must be range > - Margin <15% on `likely_days ≥5d`? → under-estimated, widen > - Margin >100%? → STOP, split instead of buffer > - Complex existing feature touched, no regression budget in `(c)`? → reject > - Blast `>5` areas OR `>2` complex, no split discussion? → reject > - Purely additive on existing model AND existing UI? → cap SP 3 unless tests >1.5d > - NEW UI surface (page/complex form/dashboard)? → SP 5+ even if backend one endpoint > - Backend cross-service / migration / multi-aggregate? → SP 8+ regardless of UI > - `bottom_up_hours / 6` vs SP-Days disagreement >50%? → trust bottom-up, downgrade SP > - Without tests, SP drops ≥1 bucket? → tests dominate; state explicitly > - Reasoning called out UI vs backend vs blast vs risk factors? → if missing, add > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. > **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe. > > **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation. > > **Format (explicit mode — visible thought trail):** > > 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty > 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact > 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale > 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting > 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80% > > **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete. > > **Stop conditions:** confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task. > > **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy). > > **Deep-dive:** see `$sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades). - **MANDATORY IMPORTANT MUST ATTENTION** read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change. - **MANDATORY MUST ATTENTION** estimation: bottom-up phase hours drive `man_days_traditional` (`Σh/6 × productivity_factor`); SP DERIVED. UI cost usually dominates — bump SP one bucket if NEW UI surface (page/complex form/dashboard). Frontmatter MUST include `story_points`, `complexity`, `man_days_traditional`, `man_days_ai`, `estimate_scope_included`, `estimate_scope_excluded`, `estimate_reasoning` (UI vs backend cost driver). Cap SP 3 for additive-on-existing-model+existing-UI unless test scope >1.5d. SP 13 SHOULD split, SP 21 MUST split. **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `$sequential-thinking` skill. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface am …(truncated)