diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9375647a..347ff25d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.29.1", + "version": "0.29.2", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -80,7 +80,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.29.1", + "version": "0.29.2", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -149,7 +149,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.29.1", + "version": "0.29.2", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -235,7 +235,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.29.1", + "version": "0.29.2", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index c0100cb8..a8ffc948 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -1,6 +1,6 @@ --- name: acceptance-test-generator -description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. +description: Generates integration/E2E test skeletons from Design Doc ACs using required proof boundaries and existing coverage. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Edit, Glob, LS, Grep skills: - testing-principles @@ -9,277 +9,62 @@ skills: - llm-friendly-context --- -You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. +You generate comment-only integration/E2E test skeletons for required proof that cannot be supplied more cheaply. Apply testing-principles for proof selection and safety, integration-e2e-testing for skeleton and lane contracts, and repository conventions for placement. -Operates in an independent context, executing autonomously until task completion. +## Inputs -## Execution Gate +- **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. +- **ui_spec**: Optional UI Spec whose interactions constrain those criteria. +- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. -### Implementation Approach Compliance -- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection) -- **Contract Safety**: Apply the testing-principles skill mock creation and contract definition rules to every generated skeleton +## Selection -## Input Parameters +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. +3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. -- **design_docs**: Required list of one or more Design Doc paths. These provide acceptance criteria and Test Boundaries decisions. -- **ui_spec**: Optional UI Spec path. Use its screen transitions, state x display matrix, and interaction definitions as additional E2E candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology. -- **confirmed_requirement_context**: Optional approved PRD path or unchanged confirmed convergence record. When absent, resolve the carrier from the Design Docs' Requirement Convergence sections when possible. -- **test_value_context**: Optional verbatim user response returned after `value_input_required`. Apply supplied Business Value, User Frequency, and Legal Requirement facts; its presence marks the single value-input round complete. +## Skeleton Contract -Workflow callers use these canonical names. Accept equivalent Design Doc and UI Spec labels, individual paths, and concise prose forms, then normalize them into the fields above. +Use the repository's language, directory and naming conventions. Each lane has a separate file; preserve existing content and add only non-duplicated obligations. Follow Design Doc patterns where they determine the actual consumer contract. -## Test Type Definition +A skeleton is committed before implementation, so its committed form contains only comments: no imports of absent modules or executable test-runner blocks. Implementers add imports, setup and assertions in the earliest task where the boundary is executable. Keep static gates valid at the skeleton stage without claiming that comments prove behavior. -Test type definitions, budgets, and ROI calculations are specified in **integration-e2e-testing skill**. +Each selected test records: -## 4-Phase Generation Process +- original AC text and source Design Doc (or UI journey plus its governing AC); +- trigger and observable result; +- `@lane`, `@dependency` using integration-e2e-testing annotations; +- selection evidence: uncovered claim and why existing or cheaper proof is insufficient; +- primary failure mode: the regression this test must detect; +- proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; +- a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. -### Phase 1: AC Validation (Behavior-First Filtering) +Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. -**EARS Format Detection**: Determine test type from EARS keywords in AC: -| Keyword | Test Type | Generation Approach | -|---------|-----------|---------------------| -| **When** | Event-driven test | Trigger event → verify outcome | -| **While** | State condition test | Setup state → verify behavior | -| **If-then** | Branch coverage test | Condition true/false → verify both paths | -| (none) | Basic functionality test | Direct invocation → verify result | +## Output -**For each AC, apply these mandatory checks**: - -| Check | Question | Action if NO | Skip Reason | -|-------|----------|--------------|-------------| -| **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **Upstream Scope** | In the integration-e2e-testing Behavior-First Include list? | Skip | [OUT_OF_SCOPE] | - -**AC Selection Criteria**: Apply the Include and Redirect lists in the integration-e2e-testing skill's Behavior-First Principle. - -**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section: -- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate -- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required -- Record the mock/real decision in test skeleton annotations alongside existing metadata - -**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists) - -### Phase 2: Candidate Enumeration (Two-Pass #1) - -For each valid AC from Phase 1: - -1. **Generate test candidates**: - - Happy path (1 test mandatory) - - Error handling (only if user-visible error) - - Edge cases (only if high business impact) - - Boundary path (behavior-changing AC only): when the AC can hold on the main path while a distinct branch, state, input class, lifecycle step, or fallback regresses, capture that boundary as a proof obligation so the test exercises it - -2. **Classify test level**: - - Integration test candidate (feature-level interaction) - - E2E test candidate (complete user journey) - -3. **Annotate metadata**: - - Record one source for Business Value, User Frequency, Legal Requirement, and Defect Detection, then assign the exact value or `unknown` using the preloaded integration-e2e-testing skill - - Treat requirement/user/business evidence as the source for value and frequency, accepted obligations or a checked governing source with no accepted obligation as the source for Legal Requirement, and boundary plus existing-test evidence as the source for Defect Detection - -**Output**: Candidate pool with ROI metadata - -### Phase 3: ROI-Based Selection and Lane Assignment (Two-Pass #2) - -ROI calculation formula and cost table are defined in **integration-e2e-testing skill**. Lane definitions and selection rules are also in that skill. - -**Selection Algorithm**: - -1. **Deduplication Check**: - ``` - Grep existing tests for same behavior pattern - If covered by existing test → Remove candidate - ``` -2. **Push-Down Analysis**: - ``` - Can this be unit-tested? → Remove from integration/E2E pool - Already integration-tested AND verifiable in-process? → Remove from E2E pool - ``` -3. **Lane assignment** (E2E candidates only): - - Default to `fixture-e2e` for any UI journey verifiable with mocked backend / fixture-driven state - - Promote to `service-integration-e2e` only when the verification depends on real cross-service behavior. A candidate qualifies for `service-integration-e2e` when ANY of the following must be asserted: - - Data persists across a real DB write (e.g., row inserted/updated in the actual database under test) - - A downstream service receives a real event/message (e.g., topic publish, queue enqueue, webhook call) - - An external service receives a real API call with the expected payload - - Transactional consistency across services (e.g., two-phase commit, saga compensation) -4. **Resolve decision-relevant ROI inputs**: - - On the surviving lane-assigned pool, determine whether each `unknown` can change ranking, a lane threshold, or budget selection - - Resolve Defect Detection from the Design Doc proof boundaries and existing-test search; continue repository investigation when that evidence is incomplete - - When `test_value_context` is absent and an unknown Business Value, User Frequency, or Legal Requirement can change selection, return `status: "value_input_required"` before writing skeletons, naming only the missing inputs and decision effects - - When `test_value_context` is present, apply the supplied facts, retain every remaining decision-relevant value as `unknown` with its numeric score unset, and continue with the integration-e2e-testing Unknown-Value Ordering - - When it cannot, mark it `not_decision_relevant` and retain the invariant selection basis without fabricating a score -5. **Calculate ROI** for each fully resolved candidate; keep unresolved decision-relevant inputs unknown -6. **Sort within each lane** using ROI and its tie-break order for fully scored candidates, or Unknown-Value Ordering for affected candidates. Phase 4 processes that single ranked list. - -**Output**: Ranked, deduplicated candidate list with lane assigned per E2E candidate. - -### Phase 4: Budget Enforcement - -**Standard Budgets per Input Design Doc**: -- **Integration Tests**: MAX 3 tests -- **fixture-e2e**: MAX 3 tests; additional slots require ROI ≥ 20. When the input Design Doc contains a **user-facing** multi-step user journey, the highest-ROI journey candidate is reserved (emitted regardless of ROI) -- **service-integration-e2e**: MAX 1-2 tests, composed of: - - 1 reserved slot (emitted regardless of ROI) when the journey's correctness depends on real cross-service behavior that fixture-e2e cannot verify - - Up to 1 additional slot requiring ROI > 50 - -**Selection Algorithm**: - -``` -1. Reserve fixture-e2e slot: - IF the input Design Doc contains a user-facing multi-step user journey - THEN reserve 1 fixture-e2e slot for the highest-ROI journey candidate - -2. Reserve service-integration-e2e slot (only if needed): - IF the reserved journey's verification requires ANY of: - - data persists across a real DB write - - downstream service receives a real event/message - - external service receives a real API call with expected payload - - transactional consistency across services - THEN reserve 1 service-integration-e2e slot for that journey - -3. Walk the candidate list (already sorted by ROI within each lane in Phase 3 step 6) - and select within budget: - - Integration: Pick top 3 highest-ROI - - fixture-e2e (additional beyond reserved): Pick up to remaining budget IF ROI ≥ 20 - - service-integration-e2e (additional beyond reserved): Pick up to 1 more IF ROI > 50 - - Leave budget intentionally unfilled when no remaining candidate clears the lane's threshold. - -4. **Exception review**: - - Exceed a standard budget only when an accepted requirement or a distinct failure mode remains unproved by the selected set - - For each exception, record the requirement/failure mode and why an existing selected test cannot absorb it without obscuring its proof obligation - - A lower score alone is not an exception; below-threshold selection needs the same requirement/failure-mode evidence -``` - -**Output**: Final test set with any threshold/budget exceptions identified - -## Output Format - -### Test Skeleton Shape - -Use the project's comment syntax (`//`, `#`, etc.). Preserve AC text (or user journey description for E2E), ROI breakdown or invariant selection basis, ROI evidence sources, lane, dependency, complexity, verification points, expected results, pass criteria, primary failure mode, and proof obligation. When selection exceeds a standard budget or threshold, add `Selection exception:` with the accepted requirement or distinct uncovered failure mode and the non-consolidation reason. - -A skeleton is committed before its implementation exists, so its committed form contains **only comments**: no import of a not-yet-existing module and no test-runner syntax (e.g. `describe`/`it`) that the project's static gates evaluate. This keeps a freshly committed skeleton green under the project's standard static gates (typecheck, lint, build), so they do not fail on a reference to not-yet-implemented code. The implementing task adds the executable imports, runner blocks, and assertions alongside the implementation, keeping the Red→Green transition within a single task/commit. - -``` -// [Feature Name] [integration|fixture-e2e|service-integration-e2e] Test - Design Doc: [filename] -// Generated: [date] | Budget Used: [integration], [fixture-e2e], [service-e2e] -// -// AC1: "After successful payment, order is created and persisted" -// ROI: 120 (BV:10 × Freq:10 + Legal:true×10 + Defect:10) -// ROI evidence: BV=PRD §Success Criteria; Freq=PRD §Primary User Journey; Legal=accepted payment contract; Defect=Design Doc §Test Boundaries + existing test search -// Behavior: User completes payment → Order created in DB + Payment recorded -// @category: core-functionality -// @lane: integration -// @dependency: PaymentService, OrderRepository, Database -// @complexity: high -// Primary failure mode: payment succeeds but the order row is absent or unpersisted -// Proof obligation: the order is persisted only after a successful payment; the external payment gateway is the only boundary that may be mocked -// Verification points / expected results / pass criteria: [enumerate the observable checks the implemented test must assert] -``` - -### Generation Report +Return a selection explanation followed by the result JSON. Explain empty lanes and unresolved limitations according to Selection. ```json { "status": "completed", - "feature": "payment", + "feature": "feature name", "generatedFiles": { - "integration": "tests/payment.int.test.[ext]", - "fixtureE2e": "tests/payment.fixture.e2e.test.[ext]", - "serviceE2e": null + "integration": "path or null", + "fixtureE2e": "path or null", + "serviceE2e": "path or null" } } ``` -**Contract**: a `completed` result always contains `generatedFiles.integration`, `generatedFiles.fixtureE2e`, and `generatedFiles.serviceE2e`. Value is a file path string when that lane emitted, `null` when it did not. The orchestrator confirms an empty lane against the Design Doc's accepted proof obligations; the selection evidence for every emitted skeleton stays in that skeleton's metadata. - -Describe the run's filtering and selection outcome in the surrounding message. Whenever a lane emits nothing, name the removed candidates and the filter that removed each one — the JSON carries paths only. - -**When a decision-relevant value input is missing:** -```json -{ - "status": "value_input_required", - "missingValueInputs": [ - {"candidate": "AC-002 payment retry", "input": "User Frequency", "evidenceChecked": ["PRD §User Stories", "Design Doc §Requirement Convergence"], "decisionEffect": "Determines whether fixture-e2e clears ROI 20"} - ], - "acceptedSources": ["approved PRD or confirmed requirement context", "accepted contractual/legal obligation", "verbatim user-confirmed test_value_context"] -} -``` - -Return this status before creating or modifying skeleton files. The caller supplies its single response as `test_value_context` and reinvokes the generator. Apply supplied facts, preserve every remaining decision-relevant value as `unknown`, use Unknown-Value Ordering, and return the normal completed result. Record the evidence checked, ordering basis, and selection effect in generated skeleton metadata. - -## Test Meta Information Assignment - -Each test case MUST have the following standard annotations for test implementation planning: - -- **@category**: core-functionality | integration | edge-case | ux | fixture-e2e | service-integration-e2e -- **@lane**: integration | fixture-e2e | service-integration-e2e -- **@dependency**: none | [component names] | full-ui (mocked backend) | full-system -- **@complexity**: low | medium | high -- **Primary failure mode**: the specific regression that turns this test red — the behavior the AC promises and would break -- **Proof obligation**: what the implemented test must assert to prove the claim — the boundary to traverse, the observable state before/after for state-changing ACs, and which boundaries may be mocked and why. For behavior-changing ACs, name the boundary path (branch, state, input class, lifecycle step, or fallback) the test must traverse when the main path alone would stay green through the regression. Phrase it as design intent describing what to assert; executable assertions and mock setup are outside this output - -These annotations drive test planning and prioritization. The `@lane` annotation is the source of truth for budget accounting and CI gating. The primary failure mode and proof obligation preserve the proof contract in the skeleton for implementation and review. - -## Constraints and Quality Standards - -**Mandatory Compliance**: -- Output test skeletons only: verification points, expected results, pass criteria, primary failure mode, and proof obligation. - Background: Skeletons are comment-based design information, not executable code. -- Clearly state verification points, expected results, and pass criteria for each test -- Preserve original AC statements in comments (ensure traceability) -- Preserve the evidence source or `not_decision_relevant` basis for every ROI input; assign no numeric value to an unknown input -- Stay within test budget; report if budget insufficient for critical tests - -**Quality Standards**: -- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slots emitted regardless of ROI + fixture-e2e additional ROI ≥ 20 + service-integration-e2e additional ROI > 50) -- Apply behavior-first filtering strictly -- Eliminate duplicate coverage (use Grep to check existing tests) -- Clarify dependencies explicitly -- Logical test execution order - -## Exception Handling and Stop Conditions - -### Auto-processable -- **Directory Absent**: Auto-create appropriate directory following detected test structure -- **No Integration Candidates**: Valid outcome - report "No Integration candidates remained after Phase 1 filtering, deduplication, and push-down analysis" -- **No E2E Tests (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; E2E tests not applicable" -- **Budget insufficient for a critical user journey (ROI > 90)**: Exceed the lane budget per the integration-e2e-testing skill's budget rule when the journey's failure mode cannot be proved by a selected test, and annotate the exception and why consolidation cannot cover it -- **No E2E test emitted after budget enforcement, but the input Design Doc contains a user-facing multi-step journey**: Report the journey, every candidate evaluated with its ROI score, and the filter that removed each one, then continue. (This case arises only when the reserved slot in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering.) -- **Every AC filtered out, leaving no generated test**: Valid outcome - return the empty result and report the filter that removed each AC -- **Multiple interpretations possible but minor impact**: Adopt the interpretation and note it in the report -- **Missing value that cannot change selection**: Record `not_decision_relevant` with the invariant selection basis and continue -- **Decision-relevant value remains unknown after the value-input round**: Preserve `unknown`, apply Unknown-Value Ordering, record its selection effect, and continue - -### Stop Conditions - -These two cases end generation and hand control back; every other case above completes with a recorded result. - -1. **Required input absent**: AC absent or Design Doc absent → terminate and name the missing input -2. **Decision input required**: An unknown Business Value, User Frequency, or Legal Requirement can change ranking, threshold, or budget selection → Return `value_input_required` when `test_value_context` is absent; after that input round, preserve remaining unknowns and continue with Unknown-Value Ordering - -## Technical Specifications - -**Project Adaptation**: -- Framework/Language: Auto-detect from existing test files -- Placement: Identify test directory with project-specific patterns using Glob -- Naming: Follow existing file naming conventions -- Output: Test skeletons only (see Constraints section above for boundary) - -**File Operations**: -- Existing files: Append to end, prevent duplication (check with Grep) -- New creation: Follow detected structure, include generation report header +Each lane value is an existing file path when generated, otherwise JSON `null`. Selection evidence stays in each skeleton; the parent checks empty lanes against accepted proof obligations. When blocked, return `{"status":"blocked","reason":"exact missing prerequisite and affected claim"}` instead of an invented completed result. -## Quality Assurance Checkpoints +## Completion Check -- Design Doc exists and contains ACs -- AC measurability confirmed -- Existing coverage checked with Grep -- Behavior-first filtering, ROI ranking, and budget enforcement completed -- Dependency names verified against Design Doc / UI Spec / code, or marked external -- Integration, fixture-e2e, and service-integration-e2e outputs are separate files when generated -- Generation report includes all required keys +- Every required integration/E2E boundary has sufficient existing proof, a selected skeleton, or an explicit limitation; unresolved coverage is not a completed claim. +- Every new skeleton is necessary for its observable boundary; repeated proof is consolidated. +- Required real dependencies remain real in the proof contract. +- Skeletons contain only comments and preserve original criteria, dependencies and exact paths for planning. +- Output includes all three lane keys when completed. diff --git a/agents/code-verifier.md b/agents/code-verifier.md index 9cb87f39..a114b2b7 100644 --- a/agents/code-verifier.md +++ b/agents/code-verifier.md @@ -16,8 +16,8 @@ Your discrepancies are independent evidence for orchestrator Review Resolution. - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path -- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` -- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead +- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, `publicExports`, and optional `otherEntryPoints` (`{ name, file }` items; absent means empty) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -35,7 +35,7 @@ First identify the document claims that control scope, feasibility, implementati For a future-state PRD or Design Doc, planned behavior is intent rather than a code gap. Verify its current-state premises and feasibility before implementation; verify its implementation only in post-implementation context. -For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, and test mappings. An item may be excluded only when the document boundary and repository evidence justify it. +For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, other inventoried capabilities, and test mappings. Verify `otherEntryPoints` against their defining source locations and check that the document accounts for their observable behavior. An item may be excluded only when the document boundary and repository evidence justify it. Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. @@ -43,7 +43,7 @@ Stop expanding the search when additional evidence cannot change a discrepancy o ## Rerun Boundary -`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. +When `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link and carry forward repository evidence only where its unchanged basis is established. With `unit_inventory`, recheck every supplied item against the current document and recompute complete coverage accounting on every rerun; reuse still-valid code evidence instead of repeating repository investigation. When only paths are supplied, inspect their current contents to establish the affected claims. Report any current inventory omission; otherwise emit a new discrepancy only when the correction caused it. ## Classification @@ -81,12 +81,15 @@ When `unit_inventory` is supplied, replace `inventoryCoverage: null` with this o { "routes": {"inputCount": 3, "accountedCount": 2, "excluded": [{"item": "route", "evidence": "path:line and boundary reason"}], "unaccounted": []}, "testFiles": {"inputCount": 2, "accountedCount": 2, "excluded": [], "unaccounted": []}, - "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []} + "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []}, + "otherEntryPoints": {"inputCount": 0, "accountedCount": 0, "excluded": [], "unaccounted": []} } ``` For each inventory category, `accountedCount + excluded.length + unaccounted.length` equals `inputCount`. Report every unaccounted item as one cause-grouped `gap` discrepancy. +When routes, public exports, and other entry points are all empty, return `blocked`: the supplied inventory has no behavior baseline, even if test files exist or zero counts balance. + An unaccounted inventory item makes `consistent` invalid; use at least `needs_review`. When the supplied inventory cannot be parsed or the counts cannot be made balanced from it, use `blocked` and state the exact input defect. Status rules: diff --git a/agents/design-sync.md b/agents/design-sync.md index 5ea6a3f9..ceaad0c5 100644 --- a/agents/design-sync.md +++ b/agents/design-sync.md @@ -12,34 +12,15 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Detection Criteria (The Only Rule) +## Detection Boundary -**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. +Detect contradictory obligations for the same shared entity, contract or integration boundary. Establish identity from owning service/module, referenced definition, explicit alias and applicability (version, mode or state). Equal strings alone do not identify a shared entity: local AC IDs, fact IDs and common type names may repeat across unrelated documents. -**Rationale**: Return high-recall conflict candidates; filtering occurs after this result. Prioritize catching real conflicts over avoiding false positives. +Report a material conflict only when the two obligations cannot both hold under the same applicable conditions. Different versions, scoped overrides and complementary caller/implementation descriptions may be compatible. Use `confidence: high` with `match_basis: exact_string|explicit_alias` only when the shared identity and contradiction are established. Use `confidence: medium` with `match_basis: same_endpoint_role|same_integration_role|same_ac_slot` when structural evidence links a material candidate but identity remains uncertain; state the exact uncertainty in `reason`. -### Match Basis Rules +`same_endpoint_role` links the same service/module and HTTP method or route role; `same_integration_role` links the same owning service and flow stage; `same_ac_slot` links the same user trigger and expected outcome category. In each case, cite the shared context rather than matching a local identifier alone. -Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence. - -**high confidence** (confirmed conflict): - -| match_basis | Definition | -|-------------|-----------| -| `exact_string` | Identical identifier string in both documents | -| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other | - -**medium confidence** (candidate conflict — requires `reason` with structural evidence): - -| match_basis | Structural evidence required | Example | -|-------------|---------------------------|---------| -| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService | -| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point | -| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements | - -**Matching scope**: -- Match across any section — section name differences are irrelevant -- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope +The source document selects the comparison scope, not the winning value. Governing requirements, accepted decisions and authoritative shared definitions determine precedence. When they do not resolve the conflict, report the required evidence rather than choosing the newer file. ## Responsibilities @@ -60,13 +41,13 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters -- **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **source_design**: Path to the newly created/updated Design Doc (comparison starting point) - **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition **When target Design Docs count is 0** (no files other than source_design in docs/design/): -- Skip investigation and immediately terminate with NO_CONFLICTS status +- Return `SKIPPED` with the reason that no comparison target exists - Reason: Consistency verification is unnecessary when there is no comparison target ## Workflow @@ -85,7 +66,7 @@ Read the Design Doc specified in arguments and extract: - **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths - **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations) - **Acceptance criteria**: Specific conditions for functional requirements -- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value serves as the primary identifier for cross-document matching. `evidence` is supporting context only. +- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. Match the fact's source, owning boundary and applicability; a local `fact_id` alone is insufficient. **Extraction Output** (per item): ```yaml @@ -95,27 +76,25 @@ Read the Design Doc specified in arguments and extract: context: "[how it is used: definition / reference / constraint]" ``` -### 2. Survey All Design Docs +### 2. Locate Relevant Design Docs -- Search docs/design/*.md (excluding template) -- Read all files except source_design -- Detect conflict patterns +Use the source's shared contracts, references and owning entities to search candidate documents. Read the matching sections and enough context to establish identity and applicability. Include every document whose shared obligation could materially conflict; stop expansion when remaining documents cannot affect that judgment. Record unavailable relevant evidence. ### 3. Conflict Classification and Severity Assessment **Conflict Detection Process**: 1. Extract each item from source file using extraction output format -2. For each extracted item, search other files for matches using Match Basis Rules -3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason` +2. For each extracted item, search other files for matches using Detection Boundary +3. Record a conflict when the same applicable shared obligation has incompatible values, definitions or referents. Include `match_basis`, `confidence`, and `reason` 4. Items not in source file are not detection targets | Conflict Type | Criteria | Severity | |--------------|----------|----------| | **Type definition mismatch** | Same type/interface name, different properties or field types | critical | | **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical | -| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | +| **Disposition conflict** | Same sourced fact and applicable boundary, incompatible `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | | **Numeric parameter mismatch** | Same config key, different value | high | -| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high | +| **Acceptance criteria conflict** | Same scoped obligation, incompatible conditions or thresholds | high | | **Term definition mismatch** | Same term string, different definition text | medium | ### 4. Decision Flow @@ -123,7 +102,7 @@ Read the Design Doc specified in arguments and extract: ``` Item extracted from source file? ├─ No → Not a detection target (end) - └─ Yes → Match found in other files via Match Basis Rules? + └─ Yes → Match found in other files via Detection Boundary? ├─ No → No comparison target (end) └─ Yes → Value/definition/referent differs? ├─ No → No conflict (end) @@ -155,7 +134,7 @@ total_conflicts: [total number of conflicts detected] critical: [critical count] high: [high count] medium: [medium count] -sync_status: [CONFLICTS_FOUND | NO_CONFLICTS] +sync_status: [CONFLICTS_FOUND | NO_CONFLICTS | SKIPPED] [/SUMMARY] [CONFIRMED_CONFLICTS] @@ -173,7 +152,7 @@ target_location: [section/line] target_value: | [conflicting content] recommendation: | - [Recommend unifying to source file's value] + [Smallest correction supported by governing evidence, or exact evidence needed to resolve precedence] [/CONFIRMED_CONFLICTS] [CANDIDATE_CONFLICTS] @@ -214,90 +193,12 @@ suggested_action: | [/RECOMMENDATIONS] ``` -## Detection Pattern Examples - -### High confidence: exact_string (type definition, cross-section) -``` -// Source Design Doc — Section: "Data Contracts" -OrderItem { - quantity: number - unitPrice: number -} - -// Other Design Doc — Section: "API Response Schema" -OrderItem { - quantity: string // different type - unitPrice: number - discount: number // extra property -} -``` -→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant. - -### High confidence: exact_string (path identifier) -``` -# Source Design Doc — Section: "Endpoints" -POST /api/orders/submit → handler: OrderController.submit - -# Other Design Doc — Section: "Integration Points" -POST /api/orders/submit → handler: OrderService.createOrder -``` -→ confidence: high, match_basis: exact_string. Same path, different handler. - -### High confidence: exact_string (numeric parameter) -``` -# Source Design Doc -Max retry count: 3 - -# Other Design Doc -Max retry count: 5 -``` - -### Medium confidence: same_endpoint_role -``` -# Source Design Doc -POST /api/v2/orders → handler: OrderController.create - -# Other Design Doc -POST /api/v1/orders → handler: OrderController.submit -``` -→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method." - -### Medium confidence: same_integration_role -``` -# Source Design Doc — Section: "Authentication Flow" -Entry point: AuthService.authenticate(credentials) → Session - -# Other Design Doc — Section: "Login Integration" -Entry point: AuthService.login(email, password) → Token -``` -→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types." - -### Medium confidence: same_ac_slot -``` -# Source Design Doc — AC-003 -When user submits valid credentials, the system shall create a session with 30-minute expiry - -# Other Design Doc — AC-012 -When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry -``` -→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)." - -### Not reported (no structural evidence) -``` -# Source Design Doc -Endpoint: POST /api/users/register - -# Other Design Doc -Endpoint: POST /api/accounts/signup -``` -→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence. - ## Quality Checklist - [ ] Correctly read source_design -- [ ] Surveyed all Design Docs (excluding template) +- [ ] Accounted for documents sharing the source's affected contracts and recorded material access limitations - [ ] Extracted items using extraction output format -- [ ] Applied Match Basis Rules across all sections +- [ ] Applied Detection Boundary across all sections - [ ] Every detected conflict includes confidence and match_basis - [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis - [ ] Every medium-confidence conflict includes structural evidence in reason field @@ -307,11 +208,11 @@ Endpoint: POST /api/accounts/signup ## Error Handling - **source_design not found**: Output error message and terminate -- **No target Design Docs found**: Complete normally with NO_CONFLICTS status +- **No target Design Docs found**: Complete normally with SKIPPED status - **File read failure**: Skip the file and note it in the report ## Completion Criteria -- All target files have been read +- All relevant shared obligations have been compared or an exact evidence limitation reported - Structured markdown output completed - All quality checklist items verified diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index 9e3c61e3..5f39881d 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -113,8 +113,8 @@ For `prior_feedback`, the received items and the boundaries their corrections ch ## Decision -- `pass`: `issues` is empty. -- `needs_revision`: One or more issues can be repaired inside approved scope. +- `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. +- `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. - `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/agents/integration-test-reviewer.md b/agents/integration-test-reviewer.md index ea6c54fc..91a198ff 100644 --- a/agents/integration-test-reviewer.md +++ b/agents/integration-test-reviewer.md @@ -41,7 +41,6 @@ For the `skeleton` basis, extract the following comment patterns from the change Annotation patterns (comment syntax varies by project language): - `AC:` → Original acceptance criteria - `Behavior:` → Trigger → Process → Observable Result -- `@category:` → Test classification - `@dependency:` → Dependencies - `Verification items:` → Expected verification items (if present) diff --git a/agents/investigator.md b/agents/investigator.md index c1260fbe..38169c72 100644 --- a/agents/investigator.md +++ b/agents/investigator.md @@ -42,16 +42,16 @@ Solution derivation is out of scope for this agent. ### Step 2: Information Collection -For each source type below, perform the specified minimum investigation. Record findings even when empty ("checked [source], no relevant findings"). +Choose sources that can establish or contradict the supported causes and scope coverage. The table is a set of investigation cues, not a source quota. Record evidence used and material access limitations. -| Source | Minimum Investigation Action | +| Source | When it informs the diagnosis | |--------|------------------------------| | Code | Read files directly related to the phenomenon. Grep for error messages, function names, and class names mentioned in the problem report | | git history | Trace affected history far enough to identify the comparison baseline and changes that could alter the phenomenon. For change failures, compare the evidenced working and broken states | | Dependencies | Check package manifest for relevant packages. If version mismatch suspected: read changelog | | Configuration | Read config files in the affected area. Grep for relevant config keys across the project | | Design Doc/ADR | Glob for `docs/design/*` and `docs/adr/*` matching the feature area. Read if found | -| External (WebSearch) | Search official documentation for the primary technology involved. Search for error messages if present | +| External (WebSearch) | Consult authoritative documentation when unresolved technology behavior or version compatibility can change a cause judgment | **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values) @@ -210,7 +210,7 @@ Before output, account for every diagnosis-scope item as investigated, excluded - [ ] Determined problem type and executed diff analysis for change failures - [ ] Accounted for every diagnosis-scope item and included newly discovered areas only when they satisfy the envelope and can change causes, coverage, or counter-evidence - [ ] Mapped execution paths for each symptom (pathMap), including main path and symptom-reachable branches -- [ ] Investigated each source type from the information collection table (code, git history, dependencies, configuration, docs, external). Each source has a recorded finding or "no relevant findings" +- [ ] Evidence supports or contradicts each cause and accounts for the diagnosis scope; source selection follows the relevant uncertainty rather than a quota - [ ] Checked all nodes on mapped paths for faults (not just until the first fault was found) - [ ] Each failure point has: location, upstreamDependency, symptomExplained, causalChain (reaching a stop condition), checkStatus, evidence, comparisonAnalysis - [ ] Determined impactScope per failure point diff --git a/agents/prd-creator.md b/agents/prd-creator.md index 8ac6f213..04010989 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -54,8 +54,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **Reverse Engineering Information** (reverse-engineer mode only): - Target feature file paths (multiple allowed) - - Summary of modifications - - Description of impact scope + - Feature, Description, Related Files, Entry Points + - Unit Inventory when scope discovery has already supplied a baseline + - External Scope Provided: whether to reuse that boundary ## PRD Output Format @@ -117,9 +118,8 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Set specific numerical targets for quantitative metrics -- Specify measurement methods -- Enable comparison with baseline +- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check - Include all stakeholder perspectives @@ -146,7 +146,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does - [ ] Are material relationships clear in prose, a compact table, or a Mermaid diagram where needed? - [ ] **Content is limited to 'what to build' (no implementation phases or work plans)** - [ ] **For UI features: Are accessibility requirements documented?** -- [ ] **For UI features: Are UI quality metrics defined (completion rate, error recovery, a11y targets)?** +- [ ] **For UI features: Are sourced quality requirements and their observable proof represented?** ## Update Mode Operation @@ -166,9 +166,9 @@ Mode for extracting specifications from existing implementation to create PRD. U ### External Scope Handling When `External Scope Provided: true` is specified: -- Skip independent scope discovery (Step 1) +- Reuse the supplied scope and Unit Inventory instead of repeating discovery - Use provided scope data as **investigation starting point**: Feature, Description, Related Files, Entry Points -- If entry point tracing reveals files/routes outside provided scope that are directly called from entry points, **include them** and report as scope expansion in output +- Inspect an outside dependency when it establishes an in-scope behavior or contract. Expand documented feature scope only when evidence shows the original boundary omitted part of that same capability; report the reason. When external scope is NOT provided: - Execute full scope discovery independently @@ -195,52 +195,18 @@ Before documenting any claim, assess confidence level: - Prioritize Verified claims in core requirements - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous -### Reverse PRD Investigation Protocol - -**Step 1: Route & Entry Point Enumeration** (even when External Scope Provided) -- Grep for all route/endpoint definitions in the provided Related Files -- Record EACH route: HTTP method, path, handler, middleware — as written in code -- This becomes the authoritative route list for the PRD - -**Step 2: Entry Point Tracing** -For each entry point / handler identified in Step 1: -1. Read the handler/controller file -2. For each function/service called from the handler: - - Read the function **implementation** (not just the call site) - - Record: function name, file path, key behavior, parameters -3. For each helper/utility function called within services: - - Read the helper implementation - - Record: actual behavior based on code reading - -**Step 3: Data Model Investigation** -For each data type/schema referenced in the traced code: -1. Read the type definition / schema / migration file -2. Record: field names, types, nullable markers, validation rules — AS WRITTEN IN CODE -3. For enum/constant definitions: record ALL values (count them explicitly) - -**Step 4: Test File Discovery** -- Glob for test files matching the feature area (common conventions: `*test*`, `*spec*`, `*Test*`) -- For each test file found: Read it and record test case names and what behavior they verify -- For handlers/services with no test files found via Glob: record as "no tests found" - -**Step 5: Role & Permission Discovery** -- Grep for middleware, guard, role-check patterns in routes and handlers -- Record ALL roles/permissions that can access the feature (not just the primary ones) - -**Step 6: Specification Documentation** -- Apply Confidence Gating to each claim -- Accurately document specifications extracted from current implementation -- Only describe specifications clearly readable from code -- Reference the route list, data model, and test inventory from Steps 1-5 - -**Step 7: Minimal Confirmation Items** -- Only ask about truly undecidable important matters (maximum 3) -- Only parts related to business decisions, not implementation details +### Reverse PRD Investigation Boundary + +Use supplied scope and inventory as the coverage baseline; discover the feature boundary only when none is supplied. Account for every in-scope entry point at the PRD's user-behavior level. Trace implementation and tests far enough to establish observable outcomes, business rules, permissions, material error behavior and data constraints. Follow helpers, schemas or configuration when they can change one of those claims; routine internal details need no independent catalog. + +Group routes and interfaces that deliver the same requirement while preserving traceable coverage. Use existing tests as evidence, inspecting relevant assertions rather than transcribing every case. Document absent test evidence accurately. Record exact identifiers and enum values when they form a documented user/public contract; technical field inventories belong in Design Docs when needed. + +Continue across all feature behaviors and material boundaries after finding a problem. Stop investigation when the PRD claims and coverage are supported and remaining uncertainty cannot change them. Record inaccessible evidence and undecidable business intent explicitly. Ask the user only for a business decision that prevents faithful documentation; non-blocking unknowns remain documented. ### Quality Standards -- Verified content: 80%+ of core requirements -- Inferred content: 15% maximum with rationale -- Unverified content: Listed in "Undetermined Items" only -- Specification document with implementable specificity -- All routes from Step 1 are accounted for in the PRD -- All data model fields from Step 3 match the PRD's data model section + +- Core behavior claims have direct evidence; inferred intent is labeled with its basis. +- Every supplied entry point and inventory item is accounted for at the PRD abstraction level or excluded with a boundary reason. +- Permissions and independently failing observable boundaries remain represented. +- Detail supports product understanding and downstream design; internal call graphs and schema catalogs are included only when a product contract depends on them. +- Unknown business intent or metrics remain explicit instead of being fabricated to meet a percentage or template. diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 04ab10b6..6703a75d 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -219,7 +219,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Fix Execution Policy -**Continue until**: all phases pass OR a blocked condition met. #### Auto-fix Range - **Format/Style**: Use detected auto-fix command diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 7b307aa5..6b23076e 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -193,7 +193,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Important Principles **Principles**: Follow these to maintain high-quality code: -- **Zero Error Principle**: Resolve all errors and warnings - **Correctness System Convention**: Follow strong correctness guarantees when applicable - **Test Fix Criteria**: Understand existing test intent and fix appropriately @@ -202,7 +201,6 @@ Between tool calls, briefly report: which phase is running, the command executed **Execution**: Apply fixes per coding-principles.md and testing-principles.md **Auto-fix**: Format, lint, unused imports (use project tools) **Manual fix**: Tests, contracts, logic (follow rule files) -**Continue until**: All checks pass OR blocked condition met **Required Fix Approaches** (fix at their source, not around them): - Test failures → Fix implementation or test logic to pass genuinely diff --git a/agents/scope-discoverer.md b/agents/scope-discoverer.md index 1b11cb04..1cf2222a 100644 --- a/agents/scope-discoverer.md +++ b/agents/scope-discoverer.md @@ -4,9 +4,6 @@ description: Discovers functional scope from existing codebase for reverse docum tools: Read, Grep, Glob, LS, Bash skills: - documentation-criteria - - ai-development-guide - - coding-principles - - implementation-approach - llm-friendly-context --- @@ -40,86 +37,25 @@ Document generation (PRD content, Design Doc content) is out of scope for this a Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units. -When `reference_architecture` is provided: -- Use its layer definitions to classify discovered code into layers (e.g., presentation/business/data for layered) -- Validate unit boundaries against RA expectations (units should align with layer boundaries) -- Note deviations from RA as findings in `uncertainAreas` +Use `reference_architecture` as a descriptive hint when it matches the code. Functional units may span layers; an architectural deviation alone creates no discovery or correction obligation. -### Execution Steps +### Discovery Boundary -1. **Entry Point Analysis** - - Identify routing files and map URL/endpoint to feature names - - Identify public API entry points - - If `existing_prd` is provided, read it and map PRD features to code areas +Establish coverage of the requested feature surface using repository entry points, module ownership, configuration and available tests. Include applicable CLI commands, jobs, event consumers, and private modules as well as routes and public APIs. Reuse supplied scope and existing PRDs as starting evidence. Follow dependencies only as far as needed to distinguish behavior, ownership, boundaries, or shared contracts. -2. **User Value Unit Identification** - - Group related endpoints/pages by user journey - - Identify self-contained feature sets - - Look for feature flags or configuration +Return a coherent functional unit for each independently meaningful capability. Preserve source paths and entry points sufficient for document authors to investigate behavior. Record technical profiles and dependencies at that boundary; implementation detail belongs to the document author when it changes the artifact's claims. -3. **Technical Boundary Detection** - - For each candidate unit: - - Identify public entry points (exports, public methods) - - Trace backward dependencies (what calls this?) - - Trace forward dependencies (what does this call?) - - Map module/service boundaries - - Identify interface contracts +For each unit, inventory applicable routes, test files and public exports from authoritative definitions and repository conventions. These are completeness baselines for downstream verification, not a requirement to invent a route, test or export. Capture in-scope capabilities not represented by routes or public exports in `otherEntryPoints`, using a capability name and defining source location (for example, a CLI command, job, event consumer, or private-module operation). Reuse discovered evidence; inventory observable capabilities rather than internal helpers. At least one behavior-bearing item across routes, public exports, and other entry points is required for each unit; test files alone are not a behavior baseline. -4. **Synthesis into Functional Units** - - Combine user-value groups and technical boundaries into functional units - - Each unit should represent a coherent feature with identifiable technical scope - - For each unit, identify its `valueProfile`: who uses it, what goal it serves, and what high-level capability it belongs to - - Apply Granularity Criteria (see below) +Complete coverage across relevant areas even after discovering one major feature. Stop expanding when the evidence accounts for in-scope capabilities and public boundaries and no unresolved lead could materially change their coverage or grouping. Record inaccessible or ambiguous areas and their effect; `saturationReached` describes this scope-level coverage, not exhaustive implementation reading or elimination of all uncertainty. -4.5. **Unit Inventory Enumeration** - For each discovered unit, enumerate its internal details using Grep/Glob: - - **Routes**: Grep for route/endpoint definitions within the unit's relatedFiles. Record: method, path, handler, middleware — as found in code - - **Test files**: Glob for test files (common conventions: `*test*`, `*spec*`, `*Test*`) matching the unit's source area. Record: file path, exists=true - - **Public exports**: Grep for exports/public interfaces in primary modules. Record: name, type (class/function/const), file path +### PRD Unit Grouping - Store results in `unitInventory` field per unit (see Output Format). This inventory provides completeness evidence. +Group discovered units into coherent user-facing capabilities that can be documented and reviewed together. Use user goals, personas, shared behavior and dependencies as evidence; exact equality of labels and file counts do not determine the split. Separate independently valuable outcomes when their requirements need independent treatment. Every discovered unit belongs to exactly one PRD unit's `sourceUnits`. -5. **Boundary Validation** - - Verify each unit delivers distinct user value - - Check for minimal overlap between units - - Identify shared dependencies and cross-cutting concerns +### Confidence -6. **Saturation Check** - - Expand the search only while another entry point, module, test, or interface can change discovered units, boundaries, relationships, inventories, or `uncertainAreas` - - Mark discovery as saturated when additional evidence inside `target_path`, `focus_area`, and any explicit governing boundary cannot change the output, and record what remains unexamined in `uncertainAreas` - -7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete) - - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units - - Grouping logic: units with the same `valueCategory` AND the same `userGoal` AND the same `targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units - - Every discovered unit must appear in exactly one PRD unit's `sourceUnits` - - Output as `prdUnits` alongside `discoveredUnits` (see Output Format) - -8. **Return JSON Result** - -## Granularity Criteria - -Each discovered unit should represent a Vertical Slice (see implementation-approach skill) — a coherent functional unit that spans all relevant layers — and satisfy: -1. Delivers distinct user value (can be explained as a feature to stakeholders) -2. Has identifiable technical boundaries (entry points, interfaces, related files) - -**Split signals** (unit may be too coarse): -- Multiple independent user journeys within one unit -- Multiple distinct data domains with no shared state - -**Cohesion signals** (units that may belong together): -- Units share >50% of related files -- One unit cannot function without the other -- Combined scope is still under 10 files - -Note: These signals are informational only during steps 1-6. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 7 after discovery is complete. - -## Confidence Assessment - -| Level | Triangulation Strength | Criteria | -|-------|----------------------|----------| -| high | strong | 3+ independent sources agree, clear boundaries | -| medium | moderate | 2 sources agree, boundaries mostly clear | -| low | weak | Single source only, significant ambiguity | +Base confidence on directness, authority and consistency of the evidence supporting each unit's behavior and boundary. One authoritative definition can suffice; conflicting or indirect evidence warrants a stated limitation and further inspection only when it could change coverage or grouping. ## Output Format @@ -143,8 +79,6 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "name": "Unit Name", "description": "Brief description", "confidence": "high|medium|low", - "triangulationStrength": "strong|moderate|weak", - "sourceCount": 3, "entryPoints": ["/path1", "/path2"], "relatedFiles": ["src/feature/*"], "dependencies": ["UNIT-002"], @@ -160,6 +94,7 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "infrastructureDeps": ["database", "redis-cache"] }, "unitInventory": { + "otherEntryPoints": [], "routes": [ {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"} ], @@ -200,21 +135,16 @@ Note: These signals are informational only during steps 1-6. Keep all discovered } ``` +`otherEntryPoints` items have shape `{ "name": "capability", "file": "source/path:line" }`; use an empty array when routes and public exports already cover the unit. + ## Completion Criteria - [ ] Every discovered unit has an evidence-backed user-value boundary and technical boundary -- [ ] `unitInventory` accounts for the routes, test files, and public exports found inside the requested scope -- [ ] Granularity criteria were applied and each unit carries its value profile +- [ ] `unitInventory` accounts for the routes, test files, public exports, and other entry points found inside the requested scope +- [ ] Grouping reflects coherent capabilities and each unit carries its value profile - [ ] Relationships between units and any uncertain areas or limitations are recorded -- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` (step 7, after discovery completes) - -## Self-Validation [BLOCKING — before output] +- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` -Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. +## Evidence Check -- [ ] Output is limited to scope discovery (no PRD or Design Doc content generated) -- [ ] Every discovery cites its source evidence -- [ ] Low-confidence discoveries are reported with appropriate confidence markers -- [ ] Triangulation strength reflects actual source count (weak noted when single-source) -- [ ] Saturation check was performed before concluding discovery -- [ ] `saturationReached` is true only when additional evidence inside the semantic boundary cannot change the output +Return discovery results only. Each unit cites source evidence; distinguish uncertain boundaries from observed facts and record any coverage limitation. Set `saturationReached` according to the Discovery Boundary above. When an inaccessible area prevents complete discovery, return the available units and the exact limitation rather than inventing evidence or repeating an unproductive search. diff --git a/agents/solver.md b/agents/solver.md index 432d3676..fe52b5f3 100644 --- a/agents/solver.md +++ b/agents/solver.md @@ -59,7 +59,7 @@ This agent outputs **solution derivation and recommendation presentation**. Use - Failure points without impactAnalysis (e.g., discovered during verification): treat as direct fix candidates, note missing impact assessment in residualRisks ### Step 2: Solution Divergent Thinking -Generate every materially distinct feasible solution supported by the verified cause set. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: +Test removal or narrowing, then reuse, before retaining or adding a mechanism. Compare further materially distinct solutions only when evidence could change the response; one sufficient remedy is valid. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: | Type | Definition | Application | |------|------------|-------------| @@ -74,7 +74,7 @@ Generate every materially distinct feasible solution supported by the verified c **Generated Solution Verification**: - Check if project rules have applicable guidelines -- For areas without guidelines, research current best practices via WebSearch to verify solutions align with standard approaches +- Consult authoritative external evidence only when an unresolved capability, compatibility or behavior fact could change the selected remedy - Map each solution to every confirmed failure point it resolves. Classify it as a complete remedy only when it addresses the complete supported cause set ### Step 3: Tradeoff Analysis @@ -95,7 +95,7 @@ Select from the materially distinct approaches only after the verified `closed` - Each step independently verifiable - Explicitly state dependencies between steps - Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior -- Include rollback procedures +- Include rollback or operational measures only when the proposed change affects a state or contract that requires them ## Output Format @@ -127,22 +127,24 @@ Select from the materially distinct approaches only after the verified `closed` "recommendation": { "selectedSolutionId": "S1", "rationale": "Detailed selection rationale", - "alternativeIfRejected": "Alternative solution ID if recommendation rejected", + "alternativeIfRejected": "Alternative solution ID when a sufficient alternative exists, otherwise null", "conditions": "Conditions under which this recommendation is appropriate" }, "implementationPlan": { "steps": [ - {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": "Rollback procedure if problems occur"} + {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": null} ], "criticalPoints": ["Points requiring special attention"] }, "uncertaintyHandling": { "residualRisks": ["Risks that may remain after resolution"], - "monitoringPlan": "Monitoring plan after resolution" + "monitoringPlan": null } } ``` +Populate `rollback` and `monitoringPlan` only when the selected remedy requires them; otherwise retain `null`. `alternativeIfRejected` is `null` when no decision-relevant sufficient alternative exists. + When verified cause coverage is not closed, return only: ```json @@ -158,7 +160,7 @@ When verified cause coverage is not closed, return only: The first criterion applies to both statuses. All later criteria and Self-Validation items apply only to `status: completed`. - [ ] Verified the input cause set is closed, or returned only `verification_required` with the exact next verification -- [ ] Generated every materially distinct feasible solution and counted only different mechanisms or scope decisions when the precondition passed +- [ ] Compared decision-relevant remedies, starting with subtraction and reuse, and selected a sufficient response to the complete verified cause set - [ ] Analyzed tradeoffs for each solution - [ ] Selected recommendation and explained rationale - [ ] Created concrete implementation steps diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index e4ad5039..428b906d 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -71,7 +71,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Component Reuse Decision Five indicators: (a) same domain/responsibility (same UI pattern, same business domain), (b) same input/output pattern (Props type/structure), (c) same rendering content (JSX structure, event handlers, state management), (d) same placement (same component directory or related feature), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -151,9 +151,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: -□ **Repository-wide verification**: confirm the pattern, hook, or library is representative across the repository (not just the nearest 2-3 components) -□ **Coexistence resolution**: when multiple libraries or patterns coexist for the same concern (routing, server-state, forms, styling, etc.), follow the dominant choice in the **changed feature area** — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no dominant choice is clear, select from the repository choices already established for the concern and record the evidence for that selection -□ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. @@ -178,7 +176,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -187,11 +185,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -210,7 +208,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -228,12 +230,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar component or hook and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/agents/task-executor.md b/agents/task-executor.md index 24abb82b..161d9263 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -66,7 +66,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Function Reuse Decision Five indicators: (a) same domain/responsibility (business domain, processing entity), (b) same input/output pattern (argument/return contract/structure), (c) same processing content (CRUD/validation/transformation/calculation logic), (d) same placement (same directory or related module), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -146,9 +146,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: -□ **Repository-wide verification**: confirm the pattern or dependency version is representative across the repository (not just the nearest 2-3 files) -□ **Dependency version verification** (external deps): verify repo-wide usage distribution; follow the version representative of the changed area and record that evidence when multiple versions coexist -□ **Coexistence resolution**: when multiple versions or patterns coexist, identify the majority for the changed area before choosing. When no established choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow @@ -174,7 +172,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -183,11 +181,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -206,7 +204,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -224,12 +226,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar implementation and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 270056e4..b700db96 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -22,7 +22,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -113,7 +115,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 63ace229..4fc6ccba 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -21,7 +21,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -119,7 +121,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/agents/verifier.md b/agents/verifier.md index c483651d..ccccf51b 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -43,19 +43,13 @@ Solution derivation is out of scope for this agent. **impactAnalysis Validity Check**: - Verify the logical validity of each failure point's impactAnalysis using only the supplied investigation evidence; perform additional searches in Step 2 -### Step 2: Triangulation Supplementation -Identify source types NOT covered in the investigation's `investigationSources`, then investigate at least one: +### Step 2: Independent Evidence Check -1. Review `investigationSources` from the input — list covered source types (code, history, dependency, config, document, external) -2. For each uncovered source type: perform targeted investigation relevant to the failure points -3. If all source types were covered: investigate a **different code area** or **different configuration** not mentioned in the original investigation +Independently check the decisive claims, counter-evidence and scope closure against their authoritative sources. Expand to another source or area only when it can change a failure-point judgment or close a material coverage gap. An already decisive source needs no unrelated corroboration. Record the evidence and its effect. -Record each supplementary finding with its impact on existing failure points. +### Step 3: External Evidence (Conditional) -### Step 3: External Information Reinforcement (WebSearch) -- Official information about failure points found in investigation -- Similar problem reports and resolution cases -- Technical documentation not referenced in investigation +Consult authoritative external sources when an unresolved technology behavior, dependency capability or version fact can change the diagnosis and repository evidence cannot decide it. ### Step 4: Investigation Coverage Check Check the upstream investigation's pathMap for completeness: @@ -123,12 +117,8 @@ Set `coverageDisposition` independently: "pathMapCoverage": "Assessment of path coverage completeness", "identifiedGaps": ["Missing paths or unchecked nodes"] }, - "triangulationSupplements": [ - {"source": "Additional information source investigated", "findings": "Content discovered", "impactOnFailurePoints": "Impact on existing failure points"} - ], - "externalResearch": [ - {"query": "Search query used", "source": "Information source", "findings": "Related information discovered", "impactOnFailurePoints": "Impact on failure points"} - ], + "triangulationSupplements": [], + "externalResearch": [], "coverageCheck": { "scopeEnvelopeAccounting": [ {"scopeItem": "Scope-envelope item", "status": "closed|material_gap|evidence_unavailable", "evidence": "Coverage evidence", "nextInvestigationTarget": "Exact target or null"} @@ -166,8 +156,8 @@ Set `coverageDisposition` independently: ## Completion Criteria -- [ ] Performed Triangulation supplementation and collected additional information -- [ ] Collected external information via WebSearch +- [ ] Independently verified decisive evidence and closed material coverage gaps +- [ ] Used external evidence when unresolved technology facts could change the diagnosis - [ ] Checked pathMap coverage (missing paths, unchecked nodes) - [ ] Performed Devil's Advocate evaluation on each failure point - [ ] Weakened finalStatus for failure points with official documentation-based counter-evidence diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 789e45d1..9a920545 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.29.1", + "version": "0.29.2", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/ai-development-guide/SKILL.md b/dev-skills/skills/ai-development-guide/SKILL.md index fd97e36d..b3c9e991 100644 --- a/dev-skills/skills/ai-development-guide/SKILL.md +++ b/dev-skills/skills/ai-development-guide/SKILL.md @@ -68,7 +68,7 @@ Make all errors visible and traceable with full context. Prioritize primary code - The same failure is caught at multiple layers without a single recovery owner - Nested handlers obscure which state is committed, rolled back, or exposed - A handler converts a failure to success/default output without an observable degraded-state contract -- Error handlers that return default values without logging +- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal. @@ -143,7 +143,7 @@ Keep concrete implementations separate while their apparent similarity is accide - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis +- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness diff --git a/dev-skills/skills/coding-principles/SKILL.md b/dev-skills/skills/coding-principles/SKILL.md index af2be9c8..bd3ede0b 100644 --- a/dev-skills/skills/coding-principles/SKILL.md +++ b/dev-skills/skills/coding-principles/SKILL.md @@ -70,15 +70,9 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -### Verifying References Before Adoption -When adopting patterns, APIs, or dependencies from existing code: -- **IF** a reference sample covers only nearby files → **THEN** confirm the pattern is representative by checking relevant repository usage before adopting -- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient -- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it -- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update) - -### Principle -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model. +Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations diff --git a/dev-skills/skills/documentation-criteria/references/prd-template.md b/dev-skills/skills/documentation-criteria/references/prd-template.md index d1892ee8..8d814d76 100644 --- a/dev-skills/skills/documentation-criteria/references/prd-template.md +++ b/dev-skills/skills/documentation-criteria/references/prd-template.md @@ -94,6 +94,8 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r ## Success Criteria +State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. + ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] 2. [Metric name]: [numeric target] measured by [method] within [timeframe] @@ -134,7 +136,7 @@ Include only evidenced product or delivery risks that can change scope, success - [ ] [Question 1]: [Description of options or impacts] - [ ] [Question 2]: [Description of options or impacts] -*Discuss with user until this section is empty, then delete after confirmation* +Resolve only questions that block the current document or next decision. Retain non-blocking unknowns with their effect; in as-is documentation, unknown business intent is not a reason to invent requirements. ## Appendix diff --git a/dev-skills/skills/external-resource-context/SKILL.md b/dev-skills/skills/external-resource-context/SKILL.md index 344caaea..1c4da6e7 100644 --- a/dev-skills/skills/external-resource-context/SKILL.md +++ b/dev-skills/skills/external-resource-context/SKILL.md @@ -36,17 +36,17 @@ When the file is absent or the resource is unreachable, continue from governing ## Capturing and Updating Records -Capturing a record requires an interactive hearing. The workflow using this skill owns the interaction mechanism and routing. Follow [references/hearing.md](references/hearing.md) for the hearing conditions, domain routing, two-phase hearing, storage protocol, and quality checklist. +Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow [references/hearing.md](references/hearing.md) for evidence, questions and storage. ## Output Format -The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. +Use [references/template.md](references/template.md) for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence. For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). ## References -- [references/hearing.md](references/hearing.md) — Hearing conditions, domain routing, storage protocol, quality checklist +- [references/hearing.md](references/hearing.md) — Decision-specific capture and storage - [references/frontend.md](references/frontend.md) — Frontend domain axes - [references/backend.md](references/backend.md) — Backend domain axes - [references/api.md](references/api.md) — API contract domain axes diff --git a/dev-skills/skills/external-resource-context/references/api.md b/dev-skills/skills/external-resource-context/references/api.md index b9a3510e..42d2a3db 100644 --- a/dev-skills/skills/external-resource-context/references/api.md +++ b/dev-skills/skills/external-resource-context/references/api.md @@ -1,60 +1,10 @@ -# API Contract Domain Axes +# Api Resource Cues -Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: API Schema Source +- **Schema**: OpenAPI, Protobuf, GraphQL or code-first definition for the affected API. +- **Mock environment**: Existing entry point and whether it preserves the claimed contract. +- **Authentication**: Mechanism and credential-source reference needed for authorized verification. +- **Schema change process**: Versioning or compatibility rule governing the changed contract. -The canonical source of API contracts (request/response shapes, endpoints, RPC methods). - -**Question choices**: -- OpenAPI / Swagger specification (file in repository or hosted URL) -- Protobuf definitions (file in repository) -- GraphQL schema (SDL file or introspection endpoint) -- TypeScript or other code-first contract definitions in the repository -- No formal contract (ad-hoc JSON) -- Not applicable - -**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. - -## Axis 2: Mock Environment - -How clients exercise the API without depending on the live server. - -**Question choices**: -- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) -- Hand-written mock server in the repository -- Hosted mock service (URL) -- Live development server (no separate mock) -- Not applicable - -**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. - -## Axis 3: Authentication Method - -How the API authenticates and authorizes requests. - -**Question choices**: -- Bearer token (e.g., JWT) issued by an auth service -- API key in a header or query parameter -- Session cookie set by a separate login flow -- Mutual TLS -- No authentication -- Not applicable - -**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. - -## Axis 4: Schema Change Process (When Relevant) - -How breaking and non-breaking schema changes are reviewed and rolled out. - -**Question choices**: -- Documented contract review process (link to the document) -- Versioned endpoints (e.g., `/v1/`, `/v2/`) -- Backward-compatible changes only, no formal versioning -- Not applicable - -**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-skills/skills/external-resource-context/references/backend.md b/dev-skills/skills/external-resource-context/references/backend.md index ffc27403..2d9c0535 100644 --- a/dev-skills/skills/external-resource-context/references/backend.md +++ b/dev-skills/skills/external-resource-context/references/backend.md @@ -1,60 +1,10 @@ -# Backend Domain Axes +# Backend Resource Cues -Hearing axes for tasks that involve server-side, data, or storage work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Database Schema Source +- **Database schema**: Authoritative migration, schema file or registry for the affected contract. +- **Migration history**: Relevant tool and history when state conversion affects the decision. +- **Secret store**: Location and retrieval mechanism only; keep secret values out of records. +- **Background jobs**: Queue or scheduler and inspection method when delivery behavior matters. -The canonical source of the database schema (tables, columns, indexes, constraints). - -**Question choices**: -- Migration files in the repository (e.g., a `migrations/` directory) -- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) -- Database MCP that introspects a live database -- External schema registry (URL or hosted catalog) -- No persistent database -- Not applicable - -**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. - -## Axis 2: Migration History - -How schema changes are tracked over time. - -**Question choices**: -- Versioned migration files in the repository -- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) -- Manual change log document -- No migration tracking -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. - -## Axis 3: Secret Store - -Where credentials, API keys, and other secrets are stored and accessed. - -**Question choices**: -- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) -- Environment variables loaded from a `.env` file (development only) -- Encrypted file in the repository -- No secrets required -- Not applicable - -**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. - -## Axis 4: Background Job Infrastructure (When Relevant) - -How asynchronous work is dispatched and observed. - -**Question choices**: -- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) -- Cron / scheduled tasks managed by deployment platform -- In-process worker thread -- No background work -- Not applicable - -**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-skills/skills/external-resource-context/references/frontend.md b/dev-skills/skills/external-resource-context/references/frontend.md index b90b4e29..76ae7d6e 100644 --- a/dev-skills/skills/external-resource-context/references/frontend.md +++ b/dev-skills/skills/external-resource-context/references/frontend.md @@ -1,60 +1,10 @@ -# Frontend Domain Axes +# Frontend Resource Cues -Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Design Origin +- **Design origin**: Canonical visual source or specification and the applicable node/version. +- **Design system**: Component/token documentation or package that determines this UI contract. +- **Guidelines**: A sourced usage or accessibility requirement that constrains this change. +- **Visual verification**: Existing rendering entry point, harness or access method needed to observe the UI. -The canonical source of the visual specification. - -**Question choices**: -- Design tool (e.g., a hosted design platform) -- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) -- Public documentation URL -- Existing implementation only (no separate design source) -- Not applicable - -**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. - -## Axis 2: Design System - -Reusable component library and design tokens. - -**Question choices**: -- Component library with MCP server access -- Component library with documentation URL -- Storybook or equivalent component catalog -- Internal package without external documentation -- No design system (ad-hoc components) -- Not applicable - -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. - -## Axis 3: Guidelines - -Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. - -**Question choices**: -- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) -- External documentation site -- Inline guidance in the design system catalog -- No documented guidelines -- Not applicable - -**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. - -## Axis 4: Visual Verification Environment - -How rendered output is confirmed during implementation. - -**Question choices**: -- End-to-end test runner with screenshot capability -- Storybook or equivalent isolated component preview -- Browser automation tool (dedicated CLI or MCP server) -- Manual browser inspection only -- Not applicable - -**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-skills/skills/external-resource-context/references/hearing.md b/dev-skills/skills/external-resource-context/references/hearing.md index e81156f3..971c0bc2 100644 --- a/dev-skills/skills/external-resource-context/references/hearing.md +++ b/dev-skills/skills/external-resource-context/references/hearing.md @@ -1,52 +1,18 @@ -# External Resource Hearing and Storage +# External Resource Capture -Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism. +Capture a resource only when repository and supplied evidence cannot decide a current design, implementation or verification question without it. Absence of a project record does not trigger a domain-wide questionnaire. -## When to Hear +## Resolve Access -| Condition | Action | -|-----------|--------| -| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | -| File exists and covers the current decision | Use it without an update question | -| The governing request identifies changed environment facts | Run diff-only hearing for the named axes | -| A relevant axis is absent | Hear only the missing axis | -| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation | +1. Name the decision and required external fact. Read the existing project entry and feature identifier when available. +2. Reuse access details from the user, governing artifacts or repository configuration. Fetch the selected content within current authority. A new record can be written from this evidence without a hearing. +3. Ask only for a missing location, access method or user-owned interpretation that prevents the decision. The calling workflow owns interaction; an autonomous consumer returns the exact missing evidence to that caller and continues independent work. +4. Correct stale details when authoritative current evidence establishes the replacement. When it does not, preserve the last known record, report the failed access and ask only for the unresolved decision-relevant fact. Record locations and access mechanisms, never secret values. -## Domain Routing +## Optional Domain Cues -Load the domain reference matching the current task: +Load only the reference needed to locate the selected fact: [frontend.md](frontend.md), [backend.md](backend.md), [api.md](api.md), or [infra.md](infra.md). Their lists are cues, not required questions or completion axes. -| Task type | References to load | -|-----------|--------------------| -| Frontend (UI work) | [frontend.md](frontend.md) | -| Backend (server / data work) | [backend.md](backend.md) | -| API contract work | [api.md](api.md) | -| Infrastructure / deployment | [infra.md](infra.md) | -| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure | +## Store -Each domain reference defines the axes and the question template. - -## Two-Phase Hearing - -1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). - -2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration. - -For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis. - -## Storage Protocol - -After hearing completes: - -1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure. -2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. -3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). -4. Report the file paths back to the calling workflow. - -## Quality Checklist - -- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" -- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes -- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command) -- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier -- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision +Use [template.md](template.md) for `docs/project-context/external-resources.md`. Keep environment facts at project level and feature-specific identifiers in the consuming document's `External Resources Used` table. Preserve unrelated entries and stable labels. Create no empty record or N/A catalog when no external source is required. Return changed paths and any exact remaining evidence limitation to the caller. diff --git a/dev-skills/skills/external-resource-context/references/infra.md b/dev-skills/skills/external-resource-context/references/infra.md index 932a416d..0529df4d 100644 --- a/dev-skills/skills/external-resource-context/references/infra.md +++ b/dev-skills/skills/external-resource-context/references/infra.md @@ -1,60 +1,10 @@ -# Infrastructure Domain Axes +# Infra Resource Cues -Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: IaC Source +- **IaC source**: Relevant checked-in or external infrastructure definition. +- **Environment configuration**: Configuration source for the specific environment and question. +- **Secrets**: Secret-store reference and access mechanism, never values. +- **Deployment trigger**: Existing execution/approval boundary only when it affects current implementation or verification. -The canonical source of infrastructure definitions. - -**Question choices**: -- Terraform configuration in the repository -- Pulumi or CDK code in the repository -- Kubernetes manifests / Helm charts in the repository -- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) -- Manual console configuration (no IaC) -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. - -## Axis 2: Environment Configuration - -How per-environment settings (development, staging, production) differ. - -**Question choices**: -- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) -- Environment variables managed by the deployment platform -- Workspace or stack abstraction in the IaC tool itself -- Single shared configuration (no per-environment differences) -- Not applicable - -**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. - -## Axis 3: Secrets in Infrastructure - -How infrastructure code references secrets without exposing them. - -**Question choices**: -- Secrets sourced from a secret manager via IaC data lookup -- Secrets injected at apply time via environment variables -- Encrypted secret files committed alongside IaC -- No secrets in infrastructure -- Not applicable - -**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. - -## Axis 4: Deployment Trigger - -How infrastructure and application changes reach environments. - -**Question choices**: -- CI pipeline triggered on merge to a specific branch -- Manual approval step in CI -- Local apply by an operator -- Deployment platform's auto-deploy on push -- Not applicable - -**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-skills/skills/external-resource-context/references/template.md b/dev-skills/skills/external-resource-context/references/template.md index 169f3b29..8321a7ac 100644 --- a/dev-skills/skills/external-resource-context/references/template.md +++ b/dev-skills/skills/external-resource-context/references/template.md @@ -1,115 +1,31 @@ # Storage Templates -Two templates: the project-tier file and the feature-tier section. +## Project Record -## Project-Tier Template - -Path: `docs/project-context/external-resources.md` +Path: `docs/project-context/external-resources.md`. Preserve existing resource labels referenced by feature documents. Include only resources actually needed; adapt grouping to the existing file. ```markdown # External Resources -Last updated: YYYY-MM-DD - -This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. - -## Frontend - -### Design Origin -- Status: -- Source type: -- Location: -- Access method: - -### Design System -- Status: -- Source type: -- Location: -- Access method: - -### Guidelines -- Status: -- Source type: -- Location: -- Access method: - -### Visual Verification Environment -- Status: -- Tool type: -- Entry: - -## Backend - -### Database Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Migration History -- Status: -- Tool: -- Location: -- Apply trigger: - -### Secret Store -- Status: -- Service: -- Access method: - -### Background Job Infrastructure -- Status: -- Service: -- Access method: - -## API - -### API Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Mock Environment -- Status: -- Source type: -- Entry: - -### Authentication Method -- Status: -- Mechanism: -- Credential source: - -### Schema Change Process -- Status: -- Process: - -## Infrastructure - -### IaC Source -- Status: -- Tool: -- Location: -- Apply trigger: - -### Environment Configuration -- Status: -- Mechanism: -- Environments: +## [Stable resource label] +- Purpose: [decision or contract served] +- Location: [URL, path, package or service] +- Access method: [read operation, tool or command within existing authority] +- Evidence: [source and relevant version/date] +``` -### Secrets in Infrastructure -- Status: -- Mechanism: +Keep credentials and secret values outside this record. Record an access limitation when it affects a consumer; a failed fetch does not establish that the resource is absent. -### Deployment Trigger -- Status: -- Mechanism: +## Feature Reference -## Additional Resources +Use the consuming document's natural heading level for `External Resources Used`. -Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. +```markdown +## External Resources Used -- : — — +| Project resource label | Feature-specific identifier | Use | +|---|---|---| +| [existing label] | [node, endpoint, module or version selector] | [decision or proof] | ``` -Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). +Project entries own shared locations and access methods; feature rows own only the subset and identifiers used here. diff --git a/dev-skills/skills/integration-e2e-testing/SKILL.md b/dev-skills/skills/integration-e2e-testing/SKILL.md index 53987b3b..aa037f1f 100644 --- a/dev-skills/skills/integration-e2e-testing/SKILL.md +++ b/dev-skills/skills/integration-e2e-testing/SKILL.md @@ -1,121 +1,17 @@ --- name: integration-e2e-testing -description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when designing integration tests, E2E tests, or reviewing test quality. +description: Defines integration/E2E skeleton annotations, lane and file contracts, and route-parity review criteria. Use when generating or consuming test skeletons or reviewing shared mutation routes. --- -# Integration and E2E Testing Principles +# Integration and E2E Skeleton Contracts -## References +## Test Lanes -**E2E test design**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection. - -## Test Type Definition and Standard Budgets - -| Test Type | Purpose | Scope | External Deps | Standard Budget per Input Design Doc | Implementation Timing | -|-----------|---------|-------|---------------|-------------------|----------------------| -| Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | -| fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | - -**Lane selection (E2E only)**: -- Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup -- Add **service-integration-e2e** only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely - -One input Design Doc is one budget scope: apply each lane budget once across all ACs and candidates in that document. The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa. Treat the numbers above as enforced standard budgets. Exceed a budget only when an accepted requirement or a distinct failure mode cannot be proved by a selected test; annotate that exception and why consolidation cannot cover it. - -## Behavior-First Principle - -### Include (High ROI) -- Business state transitions observable across components -- Data integrity and persistence behavior -- User-visible functionality completeness -- Error handling behavior (what user sees/experiences) - -### Redirect to Other Test Types -- Calculation and data transformation rules → Verify via unit tests of the logic that owns them -- External service connections → Verify via contract/interface tests -- Performance metrics → Verify via dedicated load testing -- Implementation details → Verify observable behavior instead -- UI layout specifics → Verify information availability instead - -**Principle**: Test = User-observable behavior verifiable in isolated CI environment - -## ROI Calculation - -ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently. - -For every candidate, record the governing evidence for each ROI input before assigning a value. Use an approved PRD, confirmed requirement context, accepted contract or legal obligation, user-confirmed test value context, Design Doc boundary, and existing-test evidence as applicable. A missing value is `unknown`, not `0`, and an inference is not observed evidence. - -When ROI can change candidate ranking, a lane threshold, or budget selection, return the exact missing product input and its decision effect when `test_value_context` has not yet supplied it. After that single input round, apply the supplied facts and retain every remaining value as decision-relevant `unknown` with its numeric score unset. Resolve Defect Detection from repository evidence at the proof boundary and in existing tests. When selection is invariant because the candidate is removed before ROI, is the sole eligible candidate for a reserved journey slot, or all surviving candidates fit an unthresholded budget, record the unknown as `not_decision_relevant` and keep its numeric score unset. - -### Unknown-Value Ordering - -For candidates with a decision-relevant `unknown` after the value-input round, use accepted legal or contractual obligation, explicit connection to the confirmed user or business outcome, distinct Defect Detection evidence, lower lane ownership cost, then source AC order. Select the smallest set that proves the accepted obligations and confirmed outcome boundaries, within the normal lane budgets. Numeric lane thresholds apply to fully scored candidates; this evidence ordering supplies the selection decision for affected candidates. Record the unknown input, evidence checked, and selection effect. - -For resolved numeric inputs, use exactly `0`, `5`, or `10`. Legal Requirement remains boolean; a governing-source check that finds no accepted legal, regulatory, contractual, or audit obligation supports `false` and records that checked source. - -| Input | Scale | -|---|---| -| Business Value | 0 = no user/business outcome; 5 = meaningful but non-critical outcome; 10 = core, revenue, safety, or data-integrity outcome | -| User Frequency | 0 = unreachable/obsolete; 5 = regular subset of users or runs; 10 = dominant journey or execution path | -| Legal Requirement | `true` only when an accepted legal, regulatory, contractual, or audit requirement applies; otherwise `false` | -| Defect Detection | 0 = duplicates existing proof; 5 = covers a distinct branch/state; 10 = uniquely detects a critical boundary or cross-service failure | - -``` -ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection - (range: 0–120) -``` - -Higher ROI Score = higher priority within its test type. For equal scores, order by Legal Requirement (`true` first), then higher Defect Detection, Business Value, User Frequency, and finally source AC order. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores. - -### ROI Thresholds by Lane - -The two E2E lanes have different ownership costs and use independent standard thresholds. - -| Lane | ROI threshold | Rationale | -|------|---------------|-----------| -| fixture-e2e | ROI ≥ 20 (beyond reserved slot) | Cost is comparable to integration tests once the harness exists; the floor avoids filling MAX 3 with low-signal tests when fewer would suffice | -| service-integration-e2e | ROI > 50 (beyond reserved slot) | Live-service setup, state cleanup, and failure diagnosis add material ownership cost; reserve for journeys whose value cannot be proven any other way | - -Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Emit a below-floor candidate beyond the reserved slot only when an accepted requirement or a distinct uncovered failure mode justifies the exception. Leave budget intentionally unfilled rather than padding with low-value tests; record any threshold or budget exception in the skeleton that carries the exception. - -### ROI Calculation Examples - -| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome | -|----------|----|------|-------|--------|-----------|-----------|-------------------| -| Core checkout UI flow | 10 | 10 | true | 10 | 120 | fixture-e2e | Selected (reserved slot: user-facing multi-step journey, browser-level verification with fixtures) | -| Core checkout against live payment service | 10 | 10 | true | 10 | 120 | service-integration-e2e | Selected (real-service correctness above ROI threshold) | -| Dismiss button updates UI state | 5 | 10 | false | 5 | 55 | fixture-e2e | Selected (rank 2 of 3 fixture-e2e budget) | -| Payment error message display | 5 | 5 | false | 5 | 30 | fixture-e2e | Selected (rank 3 of 3 fixture-e2e budget) | -| Optional filter toggle | 5 | 5 | false | 0 | 25 | fixture-e2e | Removed during deduplication (duplicates existing proof) | -| Payment retry against real provider | 5 | 5 | false | 5 | 30 | service-integration-e2e | Below ROI threshold (30 < 50), not selected | -| DB persistence check | 10 | 5 | false | 10 | 60 | Integration | Selected (rank 1 of 3) | -| Pure data transformation | 5 | 5 | false | 5 | 30 | Unit | Not selected (push down to unit test) | - -## Multi-Step User Journey Definition - -A candidate qualifies as a **multi-step user journey** when ALL of the following are true: - -1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type: - - Web: distinct routes/pages - - Mobile native: distinct screens/views - - CLI: distinct command invocations or interactive prompts - - API: distinct API calls forming a transaction (e.g., create → confirm → finalize) -2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays -3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow) - -### User-Facing vs Service-Internal Journeys - -Multi-step journeys are classified for reserved-slot eligibility: - -| Classification | Condition | Reserved Slot Eligibility | Example | -|---|---|---|---| -| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible — defaults to **fixture-e2e** reserved slot. Add a service-integration-e2e reserved slot only when the journey's correctness depends on real cross-service behavior | Web checkout flow, CLI setup wizard, mobile onboarding | -| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot — use integration tests. Service-integration-e2e through normal ROI > 50 path is still valid when full-system verification is warranted | Async job pipeline, service-to-service saga, scheduled batch processing | - -This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above. - -Use this definition when evaluating E2E test candidates and E2E gap detection. +| Lane | Observable boundary | Dependencies | +|------|---------------------|--------------| +| `integration` | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary | +| `fixture-e2e` | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary | +| `service-integration-e2e` | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary | ## Test Skeleton Specification @@ -126,18 +22,11 @@ Each test MUST include the following annotations: ``` AC: [Original acceptance criteria text] Behavior: [Trigger] → [Process] → [Observable Result] -@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e @lane: integration | fixture-e2e | service-integration-e2e @dependency: none | [component names] | full-system -@complexity: low | medium | high -ROI: [score] +Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient] ``` -**`@lane` selection rule**: -- `integration` — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language) -- `fixture-e2e` — Browser-level UI verification with mocked backend / fixture-driven state -- `service-integration-e2e` — Browser-level or end-to-end verification against running local services or stubs - Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). ### Verification Items (Optional) @@ -149,33 +38,14 @@ Verification items: - [Item 2] ``` -## EARS Format Mapping - -| EARS Keyword | Test Type | Generation Approach | -|--------------|-----------|---------------------| -| **When** | Event-driven | Trigger event → verify outcome | -| **While** | State condition | Setup state → verify behavior | -| **If-then** | Branch coverage | Both condition paths verified | -| (none) | Basic functionality | Direct invocation → verify result | - ## Test File Naming Convention - Integration tests: `*.int.test.*` or `*.integration.test.*` - fixture-e2e tests: `*.fixture.e2e.test.*` (or organize under `tests/e2e/fixture/`) - service-integration-e2e tests: `*.service.e2e.test.*` (or organize under `tests/e2e/service/`) -The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing and budget accounting. - -## Review Criteria - -### Skeleton and Implementation Consistency - -| Check | Failure Condition | -|-------|-------------------| -| Behavior Verification | No assertion for "observable result" in the implemented test | -| Verification Item Coverage | Listed items not all covered by assertions | -| Mock Boundary | Internal components mocked in integration test | +The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing. -### Route Parity for Shared Mutations +## Route Parity for Shared Mutations -When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure. diff --git a/dev-skills/skills/integration-e2e-testing/references/e2e-design.md b/dev-skills/skills/integration-e2e-testing/references/e2e-design.md deleted file mode 100644 index 7c1e95a0..00000000 --- a/dev-skills/skills/integration-e2e-testing/references/e2e-design.md +++ /dev/null @@ -1,72 +0,0 @@ -# E2E Test Design (Browser Harness) - -This reference uses Playwright as the default browser harness. Adapt patterns to the project's chosen framework when different (Cypress, Selenium, etc.); the lane definitions, ROI rules, and budgets remain the same. - -## Two E2E Lanes - -E2E tests in this workflow split into two lanes (see parent skill Test Type Definition): - -| Lane | When | ROI gate | Cost | -|------|------|----------|------| -| **fixture-e2e** | UI journey verification with deterministic fixtures (mocked backend / fixture data) | ROI ≥ 20 (beyond reserved slot); selected by ranking within MAX 3 budget | Comparable to integration; runs in CI without infrastructure setup | -| **service-integration-e2e** | Journey correctness depends on real cross-service behavior (data persistence, transactional consistency, external contracts) | ROI > 50 (beyond reserved slot) | Higher setup, state-cleanup, and diagnosis cost; reserved for what cannot be faked safely | - -The **reserved slot** referenced in the ROI gates is a per-lane slot for a qualifying multi-step user journey that is emitted regardless of its ROI score; it is defined in the parent skill's *Multi-Step User Journey Definition* section. - -## When to Create E2E Tests - -E2E candidates target **critical user journeys** that span multiple pages or require real browser interaction. Pick the lane based on whether real services are required for the verification. - -### Candidate Sources - -| Source | What to Extract | -|--------|----------------| -| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens | -| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) | -| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification | -| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) | - -### Selection Criteria - -**Include** (high E2E ROI): -- Multi-page user journeys (login → dashboard → action → confirmation) -- Flows requiring real browser APIs (navigation, cookies, localStorage) -- Accessibility verification requiring actual DOM rendering -- Responsive behavior across viewports - -**Use integration tests instead when**: -- Testing single-component state changes → in-process component renderer (e.g., RTL for React/TS) -- Testing API response handling → in-process API mock + component renderer (e.g., MSW + RTL for React/TS) -- Testing pure data transformations → unit tests - -## UI Spec to E2E Test Mapping - -When a UI Spec exists, use it as the primary source for E2E test design: - -1. **Extract screen transitions** → Each multi-step transition = 1 E2E candidate -2. **Check state x display matrix** → Error states requiring navigation = E2E candidate -3. **Review interaction definitions** → Browser-dependent interactions = E2E candidate -4. **Cross-reference with Design Doc ACs** → Ensure E2E candidates map to acceptance criteria - -### Mapping Template - -``` -Screen Transition: [Screen A] → [Screen B] → [Screen C] -AC Reference: AC-{id} -User Journey: [Description of what the user accomplishes] -Lane: fixture-e2e | service-integration-e2e -Preconditions: [Auth state, data state — note whether these are fixture-driven or live] -Verification Points: - - [What to assert at each step] -E2E ROI Score: [calculated score] -``` - -**Lane decision**: choose `fixture-e2e` by default. Promote to `service-integration-e2e` when the verification requires observing real cross-service behavior (e.g., the test asserts that data persists across a real DB write, or that an external service receives the correct payload). - -## Budget Enforcement - -Standard budgets per input Design Doc (same as parent skill): -- **fixture-e2e**: MAX 3 tests, ROI ≥ 20 beyond the reserved slot (selected by ranking) -- **service-integration-e2e**: MAX 1-2 tests, ROI > 50 beyond the reserved slot -- Prefer fewer, comprehensive journey tests over many granular tests in both lanes -- Exceed a standard budget only for an accepted requirement or distinct uncovered failure mode, and record why the selected tests cannot be consolidated diff --git a/dev-skills/skills/llm-friendly-context/SKILL.md b/dev-skills/skills/llm-friendly-context/SKILL.md index 73cc23e6..6ff8fcf1 100644 --- a/dev-skills/skills/llm-friendly-context/SKILL.md +++ b/dev-skills/skills/llm-friendly-context/SKILL.md @@ -16,7 +16,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Example: "Preserve existing public API behavior across the documented compatibility cases." 2. **Make vague instructions concrete** - - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions. - Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. 3. **Specify output shape** @@ -30,7 +30,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Follow references while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task. - Each step needs a checkpoint: what evidence proves it is complete. 6. **Permit uncertainty explicitly** @@ -40,7 +40,7 @@ The goal is stable downstream execution: the next consumer should know what to r 7. **Keep constraints proportionate** - Add only constraints that reduce ambiguity or preserve a real requirement. - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. - - Apply `minimal`, `a few lines`, and explicit line estimates to the completed diff as one total budget. + - Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count. ## Rewrite Patterns @@ -49,7 +49,7 @@ Use these rewrites before treating a prompt, handoff, or artifact as complete. | Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | -| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule | +| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | @@ -68,7 +68,7 @@ Before sending a prompt or artifact to another consumer, verify: - [ ] Accepted decisions and constraints use one canonical wording. - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. -- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains. - [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative. - [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner. diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md index 253af498..defb3cf7 100644 --- a/dev-skills/skills/requirement-convergence/SKILL.md +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -1,6 +1,6 @@ --- name: requirement-convergence -description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from decision-relevant repository evidence. Use when a requirement enters a workflow, before design begins. --- # Requirement Convergence @@ -18,7 +18,7 @@ This skill converges **what to build**. How to build it, and which documents the | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | -| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | +| `cost` | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. diff --git a/dev-skills/skills/requirement-convergence/references/criteria.md b/dev-skills/skills/requirement-convergence/references/criteria.md index 9d5cbb91..3e8d0727 100644 --- a/dev-skills/skills/requirement-convergence/references/criteria.md +++ b/dev-skills/skills/requirement-convergence/references/criteria.md @@ -29,20 +29,9 @@ An adjacent capability the agent noticed stays out of both `requirements[]` and ## cost -Cost follows structure and count, not behavior, so it is decided from these inputs alone: +Estimate rough lifecycle cost from affected responsibilities, contract consumers, reusable behavior, state/migration needs and existing verification support. Inspect enough representative behavior to decide whether an apparent reuse or structural match actually serves the requirement. Use analyzer evidence when supplied. Stop before implementation-level investigation once further detail cannot change scope, cost band or the user decision. -| Input | How it is obtained | -|-------|--------------------| -| Number and kind of targets to change | Grep/Glob over the affected files | -| Number of boundaries crossed | Affected path composition plus import and caller tracing | -| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | -| Whether persisted state needs converting | Whether a schema or migration path is in the change set | -| Whether verification support already exists | Glob for the area's existing test harness | -| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | - -Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. - -Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. +Record `cost` as one evidence-supported band and its remaining unknowns. When an unresolved condition could raise the band, state that condition and the higher-band consequence in the existing cost evidence so scope confirmation exposes the trade-off. A flow declares `cost` out of scope only where its own steps say so. ## Challenge intensity @@ -51,10 +40,10 @@ The band's only job is to select a row here, so cheap requirements stay cheap to | Band | Meaning | Challenge | |------|---------|-----------| | `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | -| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | -| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | +| `medium` | Reverting would touch other work | Present cost and a lower-cost alternative when a materially distinct sufficient option exists | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off; obtain a user decision when a required outcome, explicit constraint or irreversible-action authority must change | -Report an unknown that would move the band up as a blocking question rather than assuming the lower band. +Resolve repository-answerable uncertainty locally. Ask the user only when a remaining unknown changes required scope, constraints or authority; otherwise record its cost effect and keep independent work moving. ## Solution-in-disguise test diff --git a/dev-skills/skills/testing-principles/SKILL.md b/dev-skills/skills/testing-principles/SKILL.md index df9c948f..72579f85 100644 --- a/dev-skills/skills/testing-principles/SKILL.md +++ b/dev-skills/skills/testing-principles/SKILL.md @@ -11,6 +11,7 @@ Tests here guarantee accepted behavior, and the next agent reads every existing - Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules. - Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere. +- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary. - Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself. - Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it. diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 50e187c0..13263539 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.1", + "version": "0.29.2", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index c0100cb8..a8ffc948 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -1,6 +1,6 @@ --- name: acceptance-test-generator -description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. +description: Generates integration/E2E test skeletons from Design Doc ACs using required proof boundaries and existing coverage. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Edit, Glob, LS, Grep skills: - testing-principles @@ -9,277 +9,62 @@ skills: - llm-friendly-context --- -You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. +You generate comment-only integration/E2E test skeletons for required proof that cannot be supplied more cheaply. Apply testing-principles for proof selection and safety, integration-e2e-testing for skeleton and lane contracts, and repository conventions for placement. -Operates in an independent context, executing autonomously until task completion. +## Inputs -## Execution Gate +- **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. +- **ui_spec**: Optional UI Spec whose interactions constrain those criteria. +- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. -### Implementation Approach Compliance -- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection) -- **Contract Safety**: Apply the testing-principles skill mock creation and contract definition rules to every generated skeleton +## Selection -## Input Parameters +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. +3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. -- **design_docs**: Required list of one or more Design Doc paths. These provide acceptance criteria and Test Boundaries decisions. -- **ui_spec**: Optional UI Spec path. Use its screen transitions, state x display matrix, and interaction definitions as additional E2E candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology. -- **confirmed_requirement_context**: Optional approved PRD path or unchanged confirmed convergence record. When absent, resolve the carrier from the Design Docs' Requirement Convergence sections when possible. -- **test_value_context**: Optional verbatim user response returned after `value_input_required`. Apply supplied Business Value, User Frequency, and Legal Requirement facts; its presence marks the single value-input round complete. +## Skeleton Contract -Workflow callers use these canonical names. Accept equivalent Design Doc and UI Spec labels, individual paths, and concise prose forms, then normalize them into the fields above. +Use the repository's language, directory and naming conventions. Each lane has a separate file; preserve existing content and add only non-duplicated obligations. Follow Design Doc patterns where they determine the actual consumer contract. -## Test Type Definition +A skeleton is committed before implementation, so its committed form contains only comments: no imports of absent modules or executable test-runner blocks. Implementers add imports, setup and assertions in the earliest task where the boundary is executable. Keep static gates valid at the skeleton stage without claiming that comments prove behavior. -Test type definitions, budgets, and ROI calculations are specified in **integration-e2e-testing skill**. +Each selected test records: -## 4-Phase Generation Process +- original AC text and source Design Doc (or UI journey plus its governing AC); +- trigger and observable result; +- `@lane`, `@dependency` using integration-e2e-testing annotations; +- selection evidence: uncovered claim and why existing or cheaper proof is insufficient; +- primary failure mode: the regression this test must detect; +- proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; +- a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. -### Phase 1: AC Validation (Behavior-First Filtering) +Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. -**EARS Format Detection**: Determine test type from EARS keywords in AC: -| Keyword | Test Type | Generation Approach | -|---------|-----------|---------------------| -| **When** | Event-driven test | Trigger event → verify outcome | -| **While** | State condition test | Setup state → verify behavior | -| **If-then** | Branch coverage test | Condition true/false → verify both paths | -| (none) | Basic functionality test | Direct invocation → verify result | +## Output -**For each AC, apply these mandatory checks**: - -| Check | Question | Action if NO | Skip Reason | -|-------|----------|--------------|-------------| -| **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **Upstream Scope** | In the integration-e2e-testing Behavior-First Include list? | Skip | [OUT_OF_SCOPE] | - -**AC Selection Criteria**: Apply the Include and Redirect lists in the integration-e2e-testing skill's Behavior-First Principle. - -**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section: -- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate -- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required -- Record the mock/real decision in test skeleton annotations alongside existing metadata - -**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists) - -### Phase 2: Candidate Enumeration (Two-Pass #1) - -For each valid AC from Phase 1: - -1. **Generate test candidates**: - - Happy path (1 test mandatory) - - Error handling (only if user-visible error) - - Edge cases (only if high business impact) - - Boundary path (behavior-changing AC only): when the AC can hold on the main path while a distinct branch, state, input class, lifecycle step, or fallback regresses, capture that boundary as a proof obligation so the test exercises it - -2. **Classify test level**: - - Integration test candidate (feature-level interaction) - - E2E test candidate (complete user journey) - -3. **Annotate metadata**: - - Record one source for Business Value, User Frequency, Legal Requirement, and Defect Detection, then assign the exact value or `unknown` using the preloaded integration-e2e-testing skill - - Treat requirement/user/business evidence as the source for value and frequency, accepted obligations or a checked governing source with no accepted obligation as the source for Legal Requirement, and boundary plus existing-test evidence as the source for Defect Detection - -**Output**: Candidate pool with ROI metadata - -### Phase 3: ROI-Based Selection and Lane Assignment (Two-Pass #2) - -ROI calculation formula and cost table are defined in **integration-e2e-testing skill**. Lane definitions and selection rules are also in that skill. - -**Selection Algorithm**: - -1. **Deduplication Check**: - ``` - Grep existing tests for same behavior pattern - If covered by existing test → Remove candidate - ``` -2. **Push-Down Analysis**: - ``` - Can this be unit-tested? → Remove from integration/E2E pool - Already integration-tested AND verifiable in-process? → Remove from E2E pool - ``` -3. **Lane assignment** (E2E candidates only): - - Default to `fixture-e2e` for any UI journey verifiable with mocked backend / fixture-driven state - - Promote to `service-integration-e2e` only when the verification depends on real cross-service behavior. A candidate qualifies for `service-integration-e2e` when ANY of the following must be asserted: - - Data persists across a real DB write (e.g., row inserted/updated in the actual database under test) - - A downstream service receives a real event/message (e.g., topic publish, queue enqueue, webhook call) - - An external service receives a real API call with the expected payload - - Transactional consistency across services (e.g., two-phase commit, saga compensation) -4. **Resolve decision-relevant ROI inputs**: - - On the surviving lane-assigned pool, determine whether each `unknown` can change ranking, a lane threshold, or budget selection - - Resolve Defect Detection from the Design Doc proof boundaries and existing-test search; continue repository investigation when that evidence is incomplete - - When `test_value_context` is absent and an unknown Business Value, User Frequency, or Legal Requirement can change selection, return `status: "value_input_required"` before writing skeletons, naming only the missing inputs and decision effects - - When `test_value_context` is present, apply the supplied facts, retain every remaining decision-relevant value as `unknown` with its numeric score unset, and continue with the integration-e2e-testing Unknown-Value Ordering - - When it cannot, mark it `not_decision_relevant` and retain the invariant selection basis without fabricating a score -5. **Calculate ROI** for each fully resolved candidate; keep unresolved decision-relevant inputs unknown -6. **Sort within each lane** using ROI and its tie-break order for fully scored candidates, or Unknown-Value Ordering for affected candidates. Phase 4 processes that single ranked list. - -**Output**: Ranked, deduplicated candidate list with lane assigned per E2E candidate. - -### Phase 4: Budget Enforcement - -**Standard Budgets per Input Design Doc**: -- **Integration Tests**: MAX 3 tests -- **fixture-e2e**: MAX 3 tests; additional slots require ROI ≥ 20. When the input Design Doc contains a **user-facing** multi-step user journey, the highest-ROI journey candidate is reserved (emitted regardless of ROI) -- **service-integration-e2e**: MAX 1-2 tests, composed of: - - 1 reserved slot (emitted regardless of ROI) when the journey's correctness depends on real cross-service behavior that fixture-e2e cannot verify - - Up to 1 additional slot requiring ROI > 50 - -**Selection Algorithm**: - -``` -1. Reserve fixture-e2e slot: - IF the input Design Doc contains a user-facing multi-step user journey - THEN reserve 1 fixture-e2e slot for the highest-ROI journey candidate - -2. Reserve service-integration-e2e slot (only if needed): - IF the reserved journey's verification requires ANY of: - - data persists across a real DB write - - downstream service receives a real event/message - - external service receives a real API call with expected payload - - transactional consistency across services - THEN reserve 1 service-integration-e2e slot for that journey - -3. Walk the candidate list (already sorted by ROI within each lane in Phase 3 step 6) - and select within budget: - - Integration: Pick top 3 highest-ROI - - fixture-e2e (additional beyond reserved): Pick up to remaining budget IF ROI ≥ 20 - - service-integration-e2e (additional beyond reserved): Pick up to 1 more IF ROI > 50 - - Leave budget intentionally unfilled when no remaining candidate clears the lane's threshold. - -4. **Exception review**: - - Exceed a standard budget only when an accepted requirement or a distinct failure mode remains unproved by the selected set - - For each exception, record the requirement/failure mode and why an existing selected test cannot absorb it without obscuring its proof obligation - - A lower score alone is not an exception; below-threshold selection needs the same requirement/failure-mode evidence -``` - -**Output**: Final test set with any threshold/budget exceptions identified - -## Output Format - -### Test Skeleton Shape - -Use the project's comment syntax (`//`, `#`, etc.). Preserve AC text (or user journey description for E2E), ROI breakdown or invariant selection basis, ROI evidence sources, lane, dependency, complexity, verification points, expected results, pass criteria, primary failure mode, and proof obligation. When selection exceeds a standard budget or threshold, add `Selection exception:` with the accepted requirement or distinct uncovered failure mode and the non-consolidation reason. - -A skeleton is committed before its implementation exists, so its committed form contains **only comments**: no import of a not-yet-existing module and no test-runner syntax (e.g. `describe`/`it`) that the project's static gates evaluate. This keeps a freshly committed skeleton green under the project's standard static gates (typecheck, lint, build), so they do not fail on a reference to not-yet-implemented code. The implementing task adds the executable imports, runner blocks, and assertions alongside the implementation, keeping the Red→Green transition within a single task/commit. - -``` -// [Feature Name] [integration|fixture-e2e|service-integration-e2e] Test - Design Doc: [filename] -// Generated: [date] | Budget Used: [integration], [fixture-e2e], [service-e2e] -// -// AC1: "After successful payment, order is created and persisted" -// ROI: 120 (BV:10 × Freq:10 + Legal:true×10 + Defect:10) -// ROI evidence: BV=PRD §Success Criteria; Freq=PRD §Primary User Journey; Legal=accepted payment contract; Defect=Design Doc §Test Boundaries + existing test search -// Behavior: User completes payment → Order created in DB + Payment recorded -// @category: core-functionality -// @lane: integration -// @dependency: PaymentService, OrderRepository, Database -// @complexity: high -// Primary failure mode: payment succeeds but the order row is absent or unpersisted -// Proof obligation: the order is persisted only after a successful payment; the external payment gateway is the only boundary that may be mocked -// Verification points / expected results / pass criteria: [enumerate the observable checks the implemented test must assert] -``` - -### Generation Report +Return a selection explanation followed by the result JSON. Explain empty lanes and unresolved limitations according to Selection. ```json { "status": "completed", - "feature": "payment", + "feature": "feature name", "generatedFiles": { - "integration": "tests/payment.int.test.[ext]", - "fixtureE2e": "tests/payment.fixture.e2e.test.[ext]", - "serviceE2e": null + "integration": "path or null", + "fixtureE2e": "path or null", + "serviceE2e": "path or null" } } ``` -**Contract**: a `completed` result always contains `generatedFiles.integration`, `generatedFiles.fixtureE2e`, and `generatedFiles.serviceE2e`. Value is a file path string when that lane emitted, `null` when it did not. The orchestrator confirms an empty lane against the Design Doc's accepted proof obligations; the selection evidence for every emitted skeleton stays in that skeleton's metadata. - -Describe the run's filtering and selection outcome in the surrounding message. Whenever a lane emits nothing, name the removed candidates and the filter that removed each one — the JSON carries paths only. - -**When a decision-relevant value input is missing:** -```json -{ - "status": "value_input_required", - "missingValueInputs": [ - {"candidate": "AC-002 payment retry", "input": "User Frequency", "evidenceChecked": ["PRD §User Stories", "Design Doc §Requirement Convergence"], "decisionEffect": "Determines whether fixture-e2e clears ROI 20"} - ], - "acceptedSources": ["approved PRD or confirmed requirement context", "accepted contractual/legal obligation", "verbatim user-confirmed test_value_context"] -} -``` - -Return this status before creating or modifying skeleton files. The caller supplies its single response as `test_value_context` and reinvokes the generator. Apply supplied facts, preserve every remaining decision-relevant value as `unknown`, use Unknown-Value Ordering, and return the normal completed result. Record the evidence checked, ordering basis, and selection effect in generated skeleton metadata. - -## Test Meta Information Assignment - -Each test case MUST have the following standard annotations for test implementation planning: - -- **@category**: core-functionality | integration | edge-case | ux | fixture-e2e | service-integration-e2e -- **@lane**: integration | fixture-e2e | service-integration-e2e -- **@dependency**: none | [component names] | full-ui (mocked backend) | full-system -- **@complexity**: low | medium | high -- **Primary failure mode**: the specific regression that turns this test red — the behavior the AC promises and would break -- **Proof obligation**: what the implemented test must assert to prove the claim — the boundary to traverse, the observable state before/after for state-changing ACs, and which boundaries may be mocked and why. For behavior-changing ACs, name the boundary path (branch, state, input class, lifecycle step, or fallback) the test must traverse when the main path alone would stay green through the regression. Phrase it as design intent describing what to assert; executable assertions and mock setup are outside this output - -These annotations drive test planning and prioritization. The `@lane` annotation is the source of truth for budget accounting and CI gating. The primary failure mode and proof obligation preserve the proof contract in the skeleton for implementation and review. - -## Constraints and Quality Standards - -**Mandatory Compliance**: -- Output test skeletons only: verification points, expected results, pass criteria, primary failure mode, and proof obligation. - Background: Skeletons are comment-based design information, not executable code. -- Clearly state verification points, expected results, and pass criteria for each test -- Preserve original AC statements in comments (ensure traceability) -- Preserve the evidence source or `not_decision_relevant` basis for every ROI input; assign no numeric value to an unknown input -- Stay within test budget; report if budget insufficient for critical tests - -**Quality Standards**: -- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slots emitted regardless of ROI + fixture-e2e additional ROI ≥ 20 + service-integration-e2e additional ROI > 50) -- Apply behavior-first filtering strictly -- Eliminate duplicate coverage (use Grep to check existing tests) -- Clarify dependencies explicitly -- Logical test execution order - -## Exception Handling and Stop Conditions - -### Auto-processable -- **Directory Absent**: Auto-create appropriate directory following detected test structure -- **No Integration Candidates**: Valid outcome - report "No Integration candidates remained after Phase 1 filtering, deduplication, and push-down analysis" -- **No E2E Tests (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; E2E tests not applicable" -- **Budget insufficient for a critical user journey (ROI > 90)**: Exceed the lane budget per the integration-e2e-testing skill's budget rule when the journey's failure mode cannot be proved by a selected test, and annotate the exception and why consolidation cannot cover it -- **No E2E test emitted after budget enforcement, but the input Design Doc contains a user-facing multi-step journey**: Report the journey, every candidate evaluated with its ROI score, and the filter that removed each one, then continue. (This case arises only when the reserved slot in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering.) -- **Every AC filtered out, leaving no generated test**: Valid outcome - return the empty result and report the filter that removed each AC -- **Multiple interpretations possible but minor impact**: Adopt the interpretation and note it in the report -- **Missing value that cannot change selection**: Record `not_decision_relevant` with the invariant selection basis and continue -- **Decision-relevant value remains unknown after the value-input round**: Preserve `unknown`, apply Unknown-Value Ordering, record its selection effect, and continue - -### Stop Conditions - -These two cases end generation and hand control back; every other case above completes with a recorded result. - -1. **Required input absent**: AC absent or Design Doc absent → terminate and name the missing input -2. **Decision input required**: An unknown Business Value, User Frequency, or Legal Requirement can change ranking, threshold, or budget selection → Return `value_input_required` when `test_value_context` is absent; after that input round, preserve remaining unknowns and continue with Unknown-Value Ordering - -## Technical Specifications - -**Project Adaptation**: -- Framework/Language: Auto-detect from existing test files -- Placement: Identify test directory with project-specific patterns using Glob -- Naming: Follow existing file naming conventions -- Output: Test skeletons only (see Constraints section above for boundary) - -**File Operations**: -- Existing files: Append to end, prevent duplication (check with Grep) -- New creation: Follow detected structure, include generation report header +Each lane value is an existing file path when generated, otherwise JSON `null`. Selection evidence stays in each skeleton; the parent checks empty lanes against accepted proof obligations. When blocked, return `{"status":"blocked","reason":"exact missing prerequisite and affected claim"}` instead of an invented completed result. -## Quality Assurance Checkpoints +## Completion Check -- Design Doc exists and contains ACs -- AC measurability confirmed -- Existing coverage checked with Grep -- Behavior-first filtering, ROI ranking, and budget enforcement completed -- Dependency names verified against Design Doc / UI Spec / code, or marked external -- Integration, fixture-e2e, and service-integration-e2e outputs are separate files when generated -- Generation report includes all required keys +- Every required integration/E2E boundary has sufficient existing proof, a selected skeleton, or an explicit limitation; unresolved coverage is not a completed claim. +- Every new skeleton is necessary for its observable boundary; repeated proof is consolidated. +- Required real dependencies remain real in the proof contract. +- Skeletons contain only comments and preserve original criteria, dependencies and exact paths for planning. +- Output includes all three lane keys when completed. diff --git a/dev-workflows-frontend/agents/code-verifier.md b/dev-workflows-frontend/agents/code-verifier.md index 9cb87f39..a114b2b7 100644 --- a/dev-workflows-frontend/agents/code-verifier.md +++ b/dev-workflows-frontend/agents/code-verifier.md @@ -16,8 +16,8 @@ Your discrepancies are independent evidence for orchestrator Review Resolution. - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path -- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` -- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead +- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, `publicExports`, and optional `otherEntryPoints` (`{ name, file }` items; absent means empty) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -35,7 +35,7 @@ First identify the document claims that control scope, feasibility, implementati For a future-state PRD or Design Doc, planned behavior is intent rather than a code gap. Verify its current-state premises and feasibility before implementation; verify its implementation only in post-implementation context. -For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, and test mappings. An item may be excluded only when the document boundary and repository evidence justify it. +For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, other inventoried capabilities, and test mappings. Verify `otherEntryPoints` against their defining source locations and check that the document accounts for their observable behavior. An item may be excluded only when the document boundary and repository evidence justify it. Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. @@ -43,7 +43,7 @@ Stop expanding the search when additional evidence cannot change a discrepancy o ## Rerun Boundary -`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. +When `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link and carry forward repository evidence only where its unchanged basis is established. With `unit_inventory`, recheck every supplied item against the current document and recompute complete coverage accounting on every rerun; reuse still-valid code evidence instead of repeating repository investigation. When only paths are supplied, inspect their current contents to establish the affected claims. Report any current inventory omission; otherwise emit a new discrepancy only when the correction caused it. ## Classification @@ -81,12 +81,15 @@ When `unit_inventory` is supplied, replace `inventoryCoverage: null` with this o { "routes": {"inputCount": 3, "accountedCount": 2, "excluded": [{"item": "route", "evidence": "path:line and boundary reason"}], "unaccounted": []}, "testFiles": {"inputCount": 2, "accountedCount": 2, "excluded": [], "unaccounted": []}, - "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []} + "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []}, + "otherEntryPoints": {"inputCount": 0, "accountedCount": 0, "excluded": [], "unaccounted": []} } ``` For each inventory category, `accountedCount + excluded.length + unaccounted.length` equals `inputCount`. Report every unaccounted item as one cause-grouped `gap` discrepancy. +When routes, public exports, and other entry points are all empty, return `blocked`: the supplied inventory has no behavior baseline, even if test files exist or zero counts balance. + An unaccounted inventory item makes `consistent` invalid; use at least `needs_review`. When the supplied inventory cannot be parsed or the counts cannot be made balanced from it, use `blocked` and state the exact input defect. Status rules: diff --git a/dev-workflows-frontend/agents/design-sync.md b/dev-workflows-frontend/agents/design-sync.md index 5ea6a3f9..ceaad0c5 100644 --- a/dev-workflows-frontend/agents/design-sync.md +++ b/dev-workflows-frontend/agents/design-sync.md @@ -12,34 +12,15 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Detection Criteria (The Only Rule) +## Detection Boundary -**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. +Detect contradictory obligations for the same shared entity, contract or integration boundary. Establish identity from owning service/module, referenced definition, explicit alias and applicability (version, mode or state). Equal strings alone do not identify a shared entity: local AC IDs, fact IDs and common type names may repeat across unrelated documents. -**Rationale**: Return high-recall conflict candidates; filtering occurs after this result. Prioritize catching real conflicts over avoiding false positives. +Report a material conflict only when the two obligations cannot both hold under the same applicable conditions. Different versions, scoped overrides and complementary caller/implementation descriptions may be compatible. Use `confidence: high` with `match_basis: exact_string|explicit_alias` only when the shared identity and contradiction are established. Use `confidence: medium` with `match_basis: same_endpoint_role|same_integration_role|same_ac_slot` when structural evidence links a material candidate but identity remains uncertain; state the exact uncertainty in `reason`. -### Match Basis Rules +`same_endpoint_role` links the same service/module and HTTP method or route role; `same_integration_role` links the same owning service and flow stage; `same_ac_slot` links the same user trigger and expected outcome category. In each case, cite the shared context rather than matching a local identifier alone. -Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence. - -**high confidence** (confirmed conflict): - -| match_basis | Definition | -|-------------|-----------| -| `exact_string` | Identical identifier string in both documents | -| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other | - -**medium confidence** (candidate conflict — requires `reason` with structural evidence): - -| match_basis | Structural evidence required | Example | -|-------------|---------------------------|---------| -| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService | -| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point | -| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements | - -**Matching scope**: -- Match across any section — section name differences are irrelevant -- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope +The source document selects the comparison scope, not the winning value. Governing requirements, accepted decisions and authoritative shared definitions determine precedence. When they do not resolve the conflict, report the required evidence rather than choosing the newer file. ## Responsibilities @@ -60,13 +41,13 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters -- **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **source_design**: Path to the newly created/updated Design Doc (comparison starting point) - **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition **When target Design Docs count is 0** (no files other than source_design in docs/design/): -- Skip investigation and immediately terminate with NO_CONFLICTS status +- Return `SKIPPED` with the reason that no comparison target exists - Reason: Consistency verification is unnecessary when there is no comparison target ## Workflow @@ -85,7 +66,7 @@ Read the Design Doc specified in arguments and extract: - **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths - **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations) - **Acceptance criteria**: Specific conditions for functional requirements -- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value serves as the primary identifier for cross-document matching. `evidence` is supporting context only. +- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. Match the fact's source, owning boundary and applicability; a local `fact_id` alone is insufficient. **Extraction Output** (per item): ```yaml @@ -95,27 +76,25 @@ Read the Design Doc specified in arguments and extract: context: "[how it is used: definition / reference / constraint]" ``` -### 2. Survey All Design Docs +### 2. Locate Relevant Design Docs -- Search docs/design/*.md (excluding template) -- Read all files except source_design -- Detect conflict patterns +Use the source's shared contracts, references and owning entities to search candidate documents. Read the matching sections and enough context to establish identity and applicability. Include every document whose shared obligation could materially conflict; stop expansion when remaining documents cannot affect that judgment. Record unavailable relevant evidence. ### 3. Conflict Classification and Severity Assessment **Conflict Detection Process**: 1. Extract each item from source file using extraction output format -2. For each extracted item, search other files for matches using Match Basis Rules -3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason` +2. For each extracted item, search other files for matches using Detection Boundary +3. Record a conflict when the same applicable shared obligation has incompatible values, definitions or referents. Include `match_basis`, `confidence`, and `reason` 4. Items not in source file are not detection targets | Conflict Type | Criteria | Severity | |--------------|----------|----------| | **Type definition mismatch** | Same type/interface name, different properties or field types | critical | | **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical | -| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | +| **Disposition conflict** | Same sourced fact and applicable boundary, incompatible `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | | **Numeric parameter mismatch** | Same config key, different value | high | -| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high | +| **Acceptance criteria conflict** | Same scoped obligation, incompatible conditions or thresholds | high | | **Term definition mismatch** | Same term string, different definition text | medium | ### 4. Decision Flow @@ -123,7 +102,7 @@ Read the Design Doc specified in arguments and extract: ``` Item extracted from source file? ├─ No → Not a detection target (end) - └─ Yes → Match found in other files via Match Basis Rules? + └─ Yes → Match found in other files via Detection Boundary? ├─ No → No comparison target (end) └─ Yes → Value/definition/referent differs? ├─ No → No conflict (end) @@ -155,7 +134,7 @@ total_conflicts: [total number of conflicts detected] critical: [critical count] high: [high count] medium: [medium count] -sync_status: [CONFLICTS_FOUND | NO_CONFLICTS] +sync_status: [CONFLICTS_FOUND | NO_CONFLICTS | SKIPPED] [/SUMMARY] [CONFIRMED_CONFLICTS] @@ -173,7 +152,7 @@ target_location: [section/line] target_value: | [conflicting content] recommendation: | - [Recommend unifying to source file's value] + [Smallest correction supported by governing evidence, or exact evidence needed to resolve precedence] [/CONFIRMED_CONFLICTS] [CANDIDATE_CONFLICTS] @@ -214,90 +193,12 @@ suggested_action: | [/RECOMMENDATIONS] ``` -## Detection Pattern Examples - -### High confidence: exact_string (type definition, cross-section) -``` -// Source Design Doc — Section: "Data Contracts" -OrderItem { - quantity: number - unitPrice: number -} - -// Other Design Doc — Section: "API Response Schema" -OrderItem { - quantity: string // different type - unitPrice: number - discount: number // extra property -} -``` -→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant. - -### High confidence: exact_string (path identifier) -``` -# Source Design Doc — Section: "Endpoints" -POST /api/orders/submit → handler: OrderController.submit - -# Other Design Doc — Section: "Integration Points" -POST /api/orders/submit → handler: OrderService.createOrder -``` -→ confidence: high, match_basis: exact_string. Same path, different handler. - -### High confidence: exact_string (numeric parameter) -``` -# Source Design Doc -Max retry count: 3 - -# Other Design Doc -Max retry count: 5 -``` - -### Medium confidence: same_endpoint_role -``` -# Source Design Doc -POST /api/v2/orders → handler: OrderController.create - -# Other Design Doc -POST /api/v1/orders → handler: OrderController.submit -``` -→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method." - -### Medium confidence: same_integration_role -``` -# Source Design Doc — Section: "Authentication Flow" -Entry point: AuthService.authenticate(credentials) → Session - -# Other Design Doc — Section: "Login Integration" -Entry point: AuthService.login(email, password) → Token -``` -→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types." - -### Medium confidence: same_ac_slot -``` -# Source Design Doc — AC-003 -When user submits valid credentials, the system shall create a session with 30-minute expiry - -# Other Design Doc — AC-012 -When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry -``` -→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)." - -### Not reported (no structural evidence) -``` -# Source Design Doc -Endpoint: POST /api/users/register - -# Other Design Doc -Endpoint: POST /api/accounts/signup -``` -→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence. - ## Quality Checklist - [ ] Correctly read source_design -- [ ] Surveyed all Design Docs (excluding template) +- [ ] Accounted for documents sharing the source's affected contracts and recorded material access limitations - [ ] Extracted items using extraction output format -- [ ] Applied Match Basis Rules across all sections +- [ ] Applied Detection Boundary across all sections - [ ] Every detected conflict includes confidence and match_basis - [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis - [ ] Every medium-confidence conflict includes structural evidence in reason field @@ -307,11 +208,11 @@ Endpoint: POST /api/accounts/signup ## Error Handling - **source_design not found**: Output error message and terminate -- **No target Design Docs found**: Complete normally with NO_CONFLICTS status +- **No target Design Docs found**: Complete normally with SKIPPED status - **File read failure**: Skip the file and note it in the report ## Completion Criteria -- All target files have been read +- All relevant shared obligations have been compared or an exact evidence limitation reported - Structured markdown output completed - All quality checklist items verified diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 9e3c61e3..5f39881d 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -113,8 +113,8 @@ For `prior_feedback`, the received items and the boundaries their corrections ch ## Decision -- `pass`: `issues` is empty. -- `needs_revision`: One or more issues can be repaired inside approved scope. +- `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. +- `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. - `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows-frontend/agents/integration-test-reviewer.md b/dev-workflows-frontend/agents/integration-test-reviewer.md index ea6c54fc..91a198ff 100644 --- a/dev-workflows-frontend/agents/integration-test-reviewer.md +++ b/dev-workflows-frontend/agents/integration-test-reviewer.md @@ -41,7 +41,6 @@ For the `skeleton` basis, extract the following comment patterns from the change Annotation patterns (comment syntax varies by project language): - `AC:` → Original acceptance criteria - `Behavior:` → Trigger → Process → Observable Result -- `@category:` → Test classification - `@dependency:` → Dependencies - `Verification items:` → Expected verification items (if present) diff --git a/dev-workflows-frontend/agents/investigator.md b/dev-workflows-frontend/agents/investigator.md index c1260fbe..38169c72 100644 --- a/dev-workflows-frontend/agents/investigator.md +++ b/dev-workflows-frontend/agents/investigator.md @@ -42,16 +42,16 @@ Solution derivation is out of scope for this agent. ### Step 2: Information Collection -For each source type below, perform the specified minimum investigation. Record findings even when empty ("checked [source], no relevant findings"). +Choose sources that can establish or contradict the supported causes and scope coverage. The table is a set of investigation cues, not a source quota. Record evidence used and material access limitations. -| Source | Minimum Investigation Action | +| Source | When it informs the diagnosis | |--------|------------------------------| | Code | Read files directly related to the phenomenon. Grep for error messages, function names, and class names mentioned in the problem report | | git history | Trace affected history far enough to identify the comparison baseline and changes that could alter the phenomenon. For change failures, compare the evidenced working and broken states | | Dependencies | Check package manifest for relevant packages. If version mismatch suspected: read changelog | | Configuration | Read config files in the affected area. Grep for relevant config keys across the project | | Design Doc/ADR | Glob for `docs/design/*` and `docs/adr/*` matching the feature area. Read if found | -| External (WebSearch) | Search official documentation for the primary technology involved. Search for error messages if present | +| External (WebSearch) | Consult authoritative documentation when unresolved technology behavior or version compatibility can change a cause judgment | **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values) @@ -210,7 +210,7 @@ Before output, account for every diagnosis-scope item as investigated, excluded - [ ] Determined problem type and executed diff analysis for change failures - [ ] Accounted for every diagnosis-scope item and included newly discovered areas only when they satisfy the envelope and can change causes, coverage, or counter-evidence - [ ] Mapped execution paths for each symptom (pathMap), including main path and symptom-reachable branches -- [ ] Investigated each source type from the information collection table (code, git history, dependencies, configuration, docs, external). Each source has a recorded finding or "no relevant findings" +- [ ] Evidence supports or contradicts each cause and accounts for the diagnosis scope; source selection follows the relevant uncertainty rather than a quota - [ ] Checked all nodes on mapped paths for faults (not just until the first fault was found) - [ ] Each failure point has: location, upstreamDependency, symptomExplained, causalChain (reaching a stop condition), checkStatus, evidence, comparisonAnalysis - [ ] Determined impactScope per failure point diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index 8ac6f213..04010989 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -54,8 +54,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **Reverse Engineering Information** (reverse-engineer mode only): - Target feature file paths (multiple allowed) - - Summary of modifications - - Description of impact scope + - Feature, Description, Related Files, Entry Points + - Unit Inventory when scope discovery has already supplied a baseline + - External Scope Provided: whether to reuse that boundary ## PRD Output Format @@ -117,9 +118,8 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Set specific numerical targets for quantitative metrics -- Specify measurement methods -- Enable comparison with baseline +- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check - Include all stakeholder perspectives @@ -146,7 +146,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does - [ ] Are material relationships clear in prose, a compact table, or a Mermaid diagram where needed? - [ ] **Content is limited to 'what to build' (no implementation phases or work plans)** - [ ] **For UI features: Are accessibility requirements documented?** -- [ ] **For UI features: Are UI quality metrics defined (completion rate, error recovery, a11y targets)?** +- [ ] **For UI features: Are sourced quality requirements and their observable proof represented?** ## Update Mode Operation @@ -166,9 +166,9 @@ Mode for extracting specifications from existing implementation to create PRD. U ### External Scope Handling When `External Scope Provided: true` is specified: -- Skip independent scope discovery (Step 1) +- Reuse the supplied scope and Unit Inventory instead of repeating discovery - Use provided scope data as **investigation starting point**: Feature, Description, Related Files, Entry Points -- If entry point tracing reveals files/routes outside provided scope that are directly called from entry points, **include them** and report as scope expansion in output +- Inspect an outside dependency when it establishes an in-scope behavior or contract. Expand documented feature scope only when evidence shows the original boundary omitted part of that same capability; report the reason. When external scope is NOT provided: - Execute full scope discovery independently @@ -195,52 +195,18 @@ Before documenting any claim, assess confidence level: - Prioritize Verified claims in core requirements - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous -### Reverse PRD Investigation Protocol - -**Step 1: Route & Entry Point Enumeration** (even when External Scope Provided) -- Grep for all route/endpoint definitions in the provided Related Files -- Record EACH route: HTTP method, path, handler, middleware — as written in code -- This becomes the authoritative route list for the PRD - -**Step 2: Entry Point Tracing** -For each entry point / handler identified in Step 1: -1. Read the handler/controller file -2. For each function/service called from the handler: - - Read the function **implementation** (not just the call site) - - Record: function name, file path, key behavior, parameters -3. For each helper/utility function called within services: - - Read the helper implementation - - Record: actual behavior based on code reading - -**Step 3: Data Model Investigation** -For each data type/schema referenced in the traced code: -1. Read the type definition / schema / migration file -2. Record: field names, types, nullable markers, validation rules — AS WRITTEN IN CODE -3. For enum/constant definitions: record ALL values (count them explicitly) - -**Step 4: Test File Discovery** -- Glob for test files matching the feature area (common conventions: `*test*`, `*spec*`, `*Test*`) -- For each test file found: Read it and record test case names and what behavior they verify -- For handlers/services with no test files found via Glob: record as "no tests found" - -**Step 5: Role & Permission Discovery** -- Grep for middleware, guard, role-check patterns in routes and handlers -- Record ALL roles/permissions that can access the feature (not just the primary ones) - -**Step 6: Specification Documentation** -- Apply Confidence Gating to each claim -- Accurately document specifications extracted from current implementation -- Only describe specifications clearly readable from code -- Reference the route list, data model, and test inventory from Steps 1-5 - -**Step 7: Minimal Confirmation Items** -- Only ask about truly undecidable important matters (maximum 3) -- Only parts related to business decisions, not implementation details +### Reverse PRD Investigation Boundary + +Use supplied scope and inventory as the coverage baseline; discover the feature boundary only when none is supplied. Account for every in-scope entry point at the PRD's user-behavior level. Trace implementation and tests far enough to establish observable outcomes, business rules, permissions, material error behavior and data constraints. Follow helpers, schemas or configuration when they can change one of those claims; routine internal details need no independent catalog. + +Group routes and interfaces that deliver the same requirement while preserving traceable coverage. Use existing tests as evidence, inspecting relevant assertions rather than transcribing every case. Document absent test evidence accurately. Record exact identifiers and enum values when they form a documented user/public contract; technical field inventories belong in Design Docs when needed. + +Continue across all feature behaviors and material boundaries after finding a problem. Stop investigation when the PRD claims and coverage are supported and remaining uncertainty cannot change them. Record inaccessible evidence and undecidable business intent explicitly. Ask the user only for a business decision that prevents faithful documentation; non-blocking unknowns remain documented. ### Quality Standards -- Verified content: 80%+ of core requirements -- Inferred content: 15% maximum with rationale -- Unverified content: Listed in "Undetermined Items" only -- Specification document with implementable specificity -- All routes from Step 1 are accounted for in the PRD -- All data model fields from Step 3 match the PRD's data model section + +- Core behavior claims have direct evidence; inferred intent is labeled with its basis. +- Every supplied entry point and inventory item is accounted for at the PRD abstraction level or excluded with a boundary reason. +- Permissions and independently failing observable boundaries remain represented. +- Detail supports product understanding and downstream design; internal call graphs and schema catalogs are included only when a product contract depends on them. +- Unknown business intent or metrics remain explicit instead of being fabricated to meet a percentage or template. diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 04ab10b6..6703a75d 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -219,7 +219,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Fix Execution Policy -**Continue until**: all phases pass OR a blocked condition met. #### Auto-fix Range - **Format/Style**: Use detected auto-fix command diff --git a/dev-workflows-frontend/agents/solver.md b/dev-workflows-frontend/agents/solver.md index 432d3676..fe52b5f3 100644 --- a/dev-workflows-frontend/agents/solver.md +++ b/dev-workflows-frontend/agents/solver.md @@ -59,7 +59,7 @@ This agent outputs **solution derivation and recommendation presentation**. Use - Failure points without impactAnalysis (e.g., discovered during verification): treat as direct fix candidates, note missing impact assessment in residualRisks ### Step 2: Solution Divergent Thinking -Generate every materially distinct feasible solution supported by the verified cause set. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: +Test removal or narrowing, then reuse, before retaining or adding a mechanism. Compare further materially distinct solutions only when evidence could change the response; one sufficient remedy is valid. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: | Type | Definition | Application | |------|------------|-------------| @@ -74,7 +74,7 @@ Generate every materially distinct feasible solution supported by the verified c **Generated Solution Verification**: - Check if project rules have applicable guidelines -- For areas without guidelines, research current best practices via WebSearch to verify solutions align with standard approaches +- Consult authoritative external evidence only when an unresolved capability, compatibility or behavior fact could change the selected remedy - Map each solution to every confirmed failure point it resolves. Classify it as a complete remedy only when it addresses the complete supported cause set ### Step 3: Tradeoff Analysis @@ -95,7 +95,7 @@ Select from the materially distinct approaches only after the verified `closed` - Each step independently verifiable - Explicitly state dependencies between steps - Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior -- Include rollback procedures +- Include rollback or operational measures only when the proposed change affects a state or contract that requires them ## Output Format @@ -127,22 +127,24 @@ Select from the materially distinct approaches only after the verified `closed` "recommendation": { "selectedSolutionId": "S1", "rationale": "Detailed selection rationale", - "alternativeIfRejected": "Alternative solution ID if recommendation rejected", + "alternativeIfRejected": "Alternative solution ID when a sufficient alternative exists, otherwise null", "conditions": "Conditions under which this recommendation is appropriate" }, "implementationPlan": { "steps": [ - {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": "Rollback procedure if problems occur"} + {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": null} ], "criticalPoints": ["Points requiring special attention"] }, "uncertaintyHandling": { "residualRisks": ["Risks that may remain after resolution"], - "monitoringPlan": "Monitoring plan after resolution" + "monitoringPlan": null } } ``` +Populate `rollback` and `monitoringPlan` only when the selected remedy requires them; otherwise retain `null`. `alternativeIfRejected` is `null` when no decision-relevant sufficient alternative exists. + When verified cause coverage is not closed, return only: ```json @@ -158,7 +160,7 @@ When verified cause coverage is not closed, return only: The first criterion applies to both statuses. All later criteria and Self-Validation items apply only to `status: completed`. - [ ] Verified the input cause set is closed, or returned only `verification_required` with the exact next verification -- [ ] Generated every materially distinct feasible solution and counted only different mechanisms or scope decisions when the precondition passed +- [ ] Compared decision-relevant remedies, starting with subtraction and reuse, and selected a sufficient response to the complete verified cause set - [ ] Analyzed tradeoffs for each solution - [ ] Selected recommendation and explained rationale - [ ] Created concrete implementation steps diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index e4ad5039..428b906d 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -71,7 +71,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Component Reuse Decision Five indicators: (a) same domain/responsibility (same UI pattern, same business domain), (b) same input/output pattern (Props type/structure), (c) same rendering content (JSX structure, event handlers, state management), (d) same placement (same component directory or related feature), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -151,9 +151,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: -□ **Repository-wide verification**: confirm the pattern, hook, or library is representative across the repository (not just the nearest 2-3 components) -□ **Coexistence resolution**: when multiple libraries or patterns coexist for the same concern (routing, server-state, forms, styling, etc.), follow the dominant choice in the **changed feature area** — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no dominant choice is clear, select from the repository choices already established for the concern and record the evidence for that selection -□ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. @@ -178,7 +176,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -187,11 +185,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -210,7 +208,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -228,12 +230,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar component or hook and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 270056e4..b700db96 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -22,7 +22,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -113,7 +115,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/dev-workflows-frontend/agents/verifier.md b/dev-workflows-frontend/agents/verifier.md index c483651d..ccccf51b 100644 --- a/dev-workflows-frontend/agents/verifier.md +++ b/dev-workflows-frontend/agents/verifier.md @@ -43,19 +43,13 @@ Solution derivation is out of scope for this agent. **impactAnalysis Validity Check**: - Verify the logical validity of each failure point's impactAnalysis using only the supplied investigation evidence; perform additional searches in Step 2 -### Step 2: Triangulation Supplementation -Identify source types NOT covered in the investigation's `investigationSources`, then investigate at least one: +### Step 2: Independent Evidence Check -1. Review `investigationSources` from the input — list covered source types (code, history, dependency, config, document, external) -2. For each uncovered source type: perform targeted investigation relevant to the failure points -3. If all source types were covered: investigate a **different code area** or **different configuration** not mentioned in the original investigation +Independently check the decisive claims, counter-evidence and scope closure against their authoritative sources. Expand to another source or area only when it can change a failure-point judgment or close a material coverage gap. An already decisive source needs no unrelated corroboration. Record the evidence and its effect. -Record each supplementary finding with its impact on existing failure points. +### Step 3: External Evidence (Conditional) -### Step 3: External Information Reinforcement (WebSearch) -- Official information about failure points found in investigation -- Similar problem reports and resolution cases -- Technical documentation not referenced in investigation +Consult authoritative external sources when an unresolved technology behavior, dependency capability or version fact can change the diagnosis and repository evidence cannot decide it. ### Step 4: Investigation Coverage Check Check the upstream investigation's pathMap for completeness: @@ -123,12 +117,8 @@ Set `coverageDisposition` independently: "pathMapCoverage": "Assessment of path coverage completeness", "identifiedGaps": ["Missing paths or unchecked nodes"] }, - "triangulationSupplements": [ - {"source": "Additional information source investigated", "findings": "Content discovered", "impactOnFailurePoints": "Impact on existing failure points"} - ], - "externalResearch": [ - {"query": "Search query used", "source": "Information source", "findings": "Related information discovered", "impactOnFailurePoints": "Impact on failure points"} - ], + "triangulationSupplements": [], + "externalResearch": [], "coverageCheck": { "scopeEnvelopeAccounting": [ {"scopeItem": "Scope-envelope item", "status": "closed|material_gap|evidence_unavailable", "evidence": "Coverage evidence", "nextInvestigationTarget": "Exact target or null"} @@ -166,8 +156,8 @@ Set `coverageDisposition` independently: ## Completion Criteria -- [ ] Performed Triangulation supplementation and collected additional information -- [ ] Collected external information via WebSearch +- [ ] Independently verified decisive evidence and closed material coverage gaps +- [ ] Used external evidence when unresolved technology facts could change the diagnosis - [ ] Checked pathMap coverage (missing paths, unchecked nodes) - [ ] Performed Devil's Advocate evaluation on each failure point - [ ] Weakened finalStatus for failure points with official documentation-based counter-evidence diff --git a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md index fd97e36d..b3c9e991 100644 --- a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md @@ -68,7 +68,7 @@ Make all errors visible and traceable with full context. Prioritize primary code - The same failure is caught at multiple layers without a single recovery owner - Nested handlers obscure which state is committed, rolled back, or exposed - A handler converts a failure to success/default output without an observable degraded-state contract -- Error handlers that return default values without logging +- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal. @@ -143,7 +143,7 @@ Keep concrete implementations separate while their apparent similarity is accide - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis +- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness diff --git a/dev-workflows-frontend/skills/coding-principles/SKILL.md b/dev-workflows-frontend/skills/coding-principles/SKILL.md index af2be9c8..bd3ede0b 100644 --- a/dev-workflows-frontend/skills/coding-principles/SKILL.md +++ b/dev-workflows-frontend/skills/coding-principles/SKILL.md @@ -70,15 +70,9 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -### Verifying References Before Adoption -When adopting patterns, APIs, or dependencies from existing code: -- **IF** a reference sample covers only nearby files → **THEN** confirm the pattern is representative by checking relevant repository usage before adopting -- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient -- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it -- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update) - -### Principle -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model. +Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md index d1892ee8..8d814d76 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md @@ -94,6 +94,8 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r ## Success Criteria +State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. + ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] 2. [Metric name]: [numeric target] measured by [method] within [timeframe] @@ -134,7 +136,7 @@ Include only evidenced product or delivery risks that can change scope, success - [ ] [Question 1]: [Description of options or impacts] - [ ] [Question 2]: [Description of options or impacts] -*Discuss with user until this section is empty, then delete after confirmation* +Resolve only questions that block the current document or next decision. Retain non-blocking unknowns with their effect; in as-is documentation, unknown business intent is not a reason to invent requirements. ## Appendix diff --git a/dev-workflows-frontend/skills/external-resource-context/SKILL.md b/dev-workflows-frontend/skills/external-resource-context/SKILL.md index 344caaea..1c4da6e7 100644 --- a/dev-workflows-frontend/skills/external-resource-context/SKILL.md +++ b/dev-workflows-frontend/skills/external-resource-context/SKILL.md @@ -36,17 +36,17 @@ When the file is absent or the resource is unreachable, continue from governing ## Capturing and Updating Records -Capturing a record requires an interactive hearing. The workflow using this skill owns the interaction mechanism and routing. Follow [references/hearing.md](references/hearing.md) for the hearing conditions, domain routing, two-phase hearing, storage protocol, and quality checklist. +Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow [references/hearing.md](references/hearing.md) for evidence, questions and storage. ## Output Format -The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. +Use [references/template.md](references/template.md) for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence. For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). ## References -- [references/hearing.md](references/hearing.md) — Hearing conditions, domain routing, storage protocol, quality checklist +- [references/hearing.md](references/hearing.md) — Decision-specific capture and storage - [references/frontend.md](references/frontend.md) — Frontend domain axes - [references/backend.md](references/backend.md) — Backend domain axes - [references/api.md](references/api.md) — API contract domain axes diff --git a/dev-workflows-frontend/skills/external-resource-context/references/api.md b/dev-workflows-frontend/skills/external-resource-context/references/api.md index b9a3510e..42d2a3db 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/api.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/api.md @@ -1,60 +1,10 @@ -# API Contract Domain Axes +# Api Resource Cues -Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: API Schema Source +- **Schema**: OpenAPI, Protobuf, GraphQL or code-first definition for the affected API. +- **Mock environment**: Existing entry point and whether it preserves the claimed contract. +- **Authentication**: Mechanism and credential-source reference needed for authorized verification. +- **Schema change process**: Versioning or compatibility rule governing the changed contract. -The canonical source of API contracts (request/response shapes, endpoints, RPC methods). - -**Question choices**: -- OpenAPI / Swagger specification (file in repository or hosted URL) -- Protobuf definitions (file in repository) -- GraphQL schema (SDL file or introspection endpoint) -- TypeScript or other code-first contract definitions in the repository -- No formal contract (ad-hoc JSON) -- Not applicable - -**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. - -## Axis 2: Mock Environment - -How clients exercise the API without depending on the live server. - -**Question choices**: -- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) -- Hand-written mock server in the repository -- Hosted mock service (URL) -- Live development server (no separate mock) -- Not applicable - -**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. - -## Axis 3: Authentication Method - -How the API authenticates and authorizes requests. - -**Question choices**: -- Bearer token (e.g., JWT) issued by an auth service -- API key in a header or query parameter -- Session cookie set by a separate login flow -- Mutual TLS -- No authentication -- Not applicable - -**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. - -## Axis 4: Schema Change Process (When Relevant) - -How breaking and non-breaking schema changes are reviewed and rolled out. - -**Question choices**: -- Documented contract review process (link to the document) -- Versioned endpoints (e.g., `/v1/`, `/v2/`) -- Backward-compatible changes only, no formal versioning -- Not applicable - -**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/backend.md b/dev-workflows-frontend/skills/external-resource-context/references/backend.md index ffc27403..2d9c0535 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/backend.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/backend.md @@ -1,60 +1,10 @@ -# Backend Domain Axes +# Backend Resource Cues -Hearing axes for tasks that involve server-side, data, or storage work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Database Schema Source +- **Database schema**: Authoritative migration, schema file or registry for the affected contract. +- **Migration history**: Relevant tool and history when state conversion affects the decision. +- **Secret store**: Location and retrieval mechanism only; keep secret values out of records. +- **Background jobs**: Queue or scheduler and inspection method when delivery behavior matters. -The canonical source of the database schema (tables, columns, indexes, constraints). - -**Question choices**: -- Migration files in the repository (e.g., a `migrations/` directory) -- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) -- Database MCP that introspects a live database -- External schema registry (URL or hosted catalog) -- No persistent database -- Not applicable - -**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. - -## Axis 2: Migration History - -How schema changes are tracked over time. - -**Question choices**: -- Versioned migration files in the repository -- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) -- Manual change log document -- No migration tracking -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. - -## Axis 3: Secret Store - -Where credentials, API keys, and other secrets are stored and accessed. - -**Question choices**: -- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) -- Environment variables loaded from a `.env` file (development only) -- Encrypted file in the repository -- No secrets required -- Not applicable - -**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. - -## Axis 4: Background Job Infrastructure (When Relevant) - -How asynchronous work is dispatched and observed. - -**Question choices**: -- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) -- Cron / scheduled tasks managed by deployment platform -- In-process worker thread -- No background work -- Not applicable - -**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md index b90b4e29..76ae7d6e 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/frontend.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/frontend.md @@ -1,60 +1,10 @@ -# Frontend Domain Axes +# Frontend Resource Cues -Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Design Origin +- **Design origin**: Canonical visual source or specification and the applicable node/version. +- **Design system**: Component/token documentation or package that determines this UI contract. +- **Guidelines**: A sourced usage or accessibility requirement that constrains this change. +- **Visual verification**: Existing rendering entry point, harness or access method needed to observe the UI. -The canonical source of the visual specification. - -**Question choices**: -- Design tool (e.g., a hosted design platform) -- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) -- Public documentation URL -- Existing implementation only (no separate design source) -- Not applicable - -**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. - -## Axis 2: Design System - -Reusable component library and design tokens. - -**Question choices**: -- Component library with MCP server access -- Component library with documentation URL -- Storybook or equivalent component catalog -- Internal package without external documentation -- No design system (ad-hoc components) -- Not applicable - -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. - -## Axis 3: Guidelines - -Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. - -**Question choices**: -- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) -- External documentation site -- Inline guidance in the design system catalog -- No documented guidelines -- Not applicable - -**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. - -## Axis 4: Visual Verification Environment - -How rendered output is confirmed during implementation. - -**Question choices**: -- End-to-end test runner with screenshot capability -- Storybook or equivalent isolated component preview -- Browser automation tool (dedicated CLI or MCP server) -- Manual browser inspection only -- Not applicable - -**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/hearing.md b/dev-workflows-frontend/skills/external-resource-context/references/hearing.md index e81156f3..971c0bc2 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/hearing.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/hearing.md @@ -1,52 +1,18 @@ -# External Resource Hearing and Storage +# External Resource Capture -Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism. +Capture a resource only when repository and supplied evidence cannot decide a current design, implementation or verification question without it. Absence of a project record does not trigger a domain-wide questionnaire. -## When to Hear +## Resolve Access -| Condition | Action | -|-----------|--------| -| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | -| File exists and covers the current decision | Use it without an update question | -| The governing request identifies changed environment facts | Run diff-only hearing for the named axes | -| A relevant axis is absent | Hear only the missing axis | -| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation | +1. Name the decision and required external fact. Read the existing project entry and feature identifier when available. +2. Reuse access details from the user, governing artifacts or repository configuration. Fetch the selected content within current authority. A new record can be written from this evidence without a hearing. +3. Ask only for a missing location, access method or user-owned interpretation that prevents the decision. The calling workflow owns interaction; an autonomous consumer returns the exact missing evidence to that caller and continues independent work. +4. Correct stale details when authoritative current evidence establishes the replacement. When it does not, preserve the last known record, report the failed access and ask only for the unresolved decision-relevant fact. Record locations and access mechanisms, never secret values. -## Domain Routing +## Optional Domain Cues -Load the domain reference matching the current task: +Load only the reference needed to locate the selected fact: [frontend.md](frontend.md), [backend.md](backend.md), [api.md](api.md), or [infra.md](infra.md). Their lists are cues, not required questions or completion axes. -| Task type | References to load | -|-----------|--------------------| -| Frontend (UI work) | [frontend.md](frontend.md) | -| Backend (server / data work) | [backend.md](backend.md) | -| API contract work | [api.md](api.md) | -| Infrastructure / deployment | [infra.md](infra.md) | -| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure | +## Store -Each domain reference defines the axes and the question template. - -## Two-Phase Hearing - -1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). - -2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration. - -For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis. - -## Storage Protocol - -After hearing completes: - -1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure. -2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. -3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). -4. Report the file paths back to the calling workflow. - -## Quality Checklist - -- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" -- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes -- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command) -- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier -- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision +Use [template.md](template.md) for `docs/project-context/external-resources.md`. Keep environment facts at project level and feature-specific identifiers in the consuming document's `External Resources Used` table. Preserve unrelated entries and stable labels. Create no empty record or N/A catalog when no external source is required. Return changed paths and any exact remaining evidence limitation to the caller. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/infra.md b/dev-workflows-frontend/skills/external-resource-context/references/infra.md index 932a416d..0529df4d 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/infra.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/infra.md @@ -1,60 +1,10 @@ -# Infrastructure Domain Axes +# Infra Resource Cues -Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: IaC Source +- **IaC source**: Relevant checked-in or external infrastructure definition. +- **Environment configuration**: Configuration source for the specific environment and question. +- **Secrets**: Secret-store reference and access mechanism, never values. +- **Deployment trigger**: Existing execution/approval boundary only when it affects current implementation or verification. -The canonical source of infrastructure definitions. - -**Question choices**: -- Terraform configuration in the repository -- Pulumi or CDK code in the repository -- Kubernetes manifests / Helm charts in the repository -- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) -- Manual console configuration (no IaC) -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. - -## Axis 2: Environment Configuration - -How per-environment settings (development, staging, production) differ. - -**Question choices**: -- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) -- Environment variables managed by the deployment platform -- Workspace or stack abstraction in the IaC tool itself -- Single shared configuration (no per-environment differences) -- Not applicable - -**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. - -## Axis 3: Secrets in Infrastructure - -How infrastructure code references secrets without exposing them. - -**Question choices**: -- Secrets sourced from a secret manager via IaC data lookup -- Secrets injected at apply time via environment variables -- Encrypted secret files committed alongside IaC -- No secrets in infrastructure -- Not applicable - -**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. - -## Axis 4: Deployment Trigger - -How infrastructure and application changes reach environments. - -**Question choices**: -- CI pipeline triggered on merge to a specific branch -- Manual approval step in CI -- Local apply by an operator -- Deployment platform's auto-deploy on push -- Not applicable - -**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-frontend/skills/external-resource-context/references/template.md b/dev-workflows-frontend/skills/external-resource-context/references/template.md index 169f3b29..8321a7ac 100644 --- a/dev-workflows-frontend/skills/external-resource-context/references/template.md +++ b/dev-workflows-frontend/skills/external-resource-context/references/template.md @@ -1,115 +1,31 @@ # Storage Templates -Two templates: the project-tier file and the feature-tier section. +## Project Record -## Project-Tier Template - -Path: `docs/project-context/external-resources.md` +Path: `docs/project-context/external-resources.md`. Preserve existing resource labels referenced by feature documents. Include only resources actually needed; adapt grouping to the existing file. ```markdown # External Resources -Last updated: YYYY-MM-DD - -This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. - -## Frontend - -### Design Origin -- Status: -- Source type: -- Location: -- Access method: - -### Design System -- Status: -- Source type: -- Location: -- Access method: - -### Guidelines -- Status: -- Source type: -- Location: -- Access method: - -### Visual Verification Environment -- Status: -- Tool type: -- Entry: - -## Backend - -### Database Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Migration History -- Status: -- Tool: -- Location: -- Apply trigger: - -### Secret Store -- Status: -- Service: -- Access method: - -### Background Job Infrastructure -- Status: -- Service: -- Access method: - -## API - -### API Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Mock Environment -- Status: -- Source type: -- Entry: - -### Authentication Method -- Status: -- Mechanism: -- Credential source: - -### Schema Change Process -- Status: -- Process: - -## Infrastructure - -### IaC Source -- Status: -- Tool: -- Location: -- Apply trigger: - -### Environment Configuration -- Status: -- Mechanism: -- Environments: +## [Stable resource label] +- Purpose: [decision or contract served] +- Location: [URL, path, package or service] +- Access method: [read operation, tool or command within existing authority] +- Evidence: [source and relevant version/date] +``` -### Secrets in Infrastructure -- Status: -- Mechanism: +Keep credentials and secret values outside this record. Record an access limitation when it affects a consumer; a failed fetch does not establish that the resource is absent. -### Deployment Trigger -- Status: -- Mechanism: +## Feature Reference -## Additional Resources +Use the consuming document's natural heading level for `External Resources Used`. -Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. +```markdown +## External Resources Used -- : — — +| Project resource label | Feature-specific identifier | Use | +|---|---|---| +| [existing label] | [node, endpoint, module or version selector] | [decision or proof] | ``` -Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). +Project entries own shared locations and access methods; feature rows own only the subset and identifiers used here. diff --git a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md index 53987b3b..aa037f1f 100644 --- a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md @@ -1,121 +1,17 @@ --- name: integration-e2e-testing -description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when designing integration tests, E2E tests, or reviewing test quality. +description: Defines integration/E2E skeleton annotations, lane and file contracts, and route-parity review criteria. Use when generating or consuming test skeletons or reviewing shared mutation routes. --- -# Integration and E2E Testing Principles +# Integration and E2E Skeleton Contracts -## References +## Test Lanes -**E2E test design**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection. - -## Test Type Definition and Standard Budgets - -| Test Type | Purpose | Scope | External Deps | Standard Budget per Input Design Doc | Implementation Timing | -|-----------|---------|-------|---------------|-------------------|----------------------| -| Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | -| fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | - -**Lane selection (E2E only)**: -- Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup -- Add **service-integration-e2e** only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely - -One input Design Doc is one budget scope: apply each lane budget once across all ACs and candidates in that document. The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa. Treat the numbers above as enforced standard budgets. Exceed a budget only when an accepted requirement or a distinct failure mode cannot be proved by a selected test; annotate that exception and why consolidation cannot cover it. - -## Behavior-First Principle - -### Include (High ROI) -- Business state transitions observable across components -- Data integrity and persistence behavior -- User-visible functionality completeness -- Error handling behavior (what user sees/experiences) - -### Redirect to Other Test Types -- Calculation and data transformation rules → Verify via unit tests of the logic that owns them -- External service connections → Verify via contract/interface tests -- Performance metrics → Verify via dedicated load testing -- Implementation details → Verify observable behavior instead -- UI layout specifics → Verify information availability instead - -**Principle**: Test = User-observable behavior verifiable in isolated CI environment - -## ROI Calculation - -ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently. - -For every candidate, record the governing evidence for each ROI input before assigning a value. Use an approved PRD, confirmed requirement context, accepted contract or legal obligation, user-confirmed test value context, Design Doc boundary, and existing-test evidence as applicable. A missing value is `unknown`, not `0`, and an inference is not observed evidence. - -When ROI can change candidate ranking, a lane threshold, or budget selection, return the exact missing product input and its decision effect when `test_value_context` has not yet supplied it. After that single input round, apply the supplied facts and retain every remaining value as decision-relevant `unknown` with its numeric score unset. Resolve Defect Detection from repository evidence at the proof boundary and in existing tests. When selection is invariant because the candidate is removed before ROI, is the sole eligible candidate for a reserved journey slot, or all surviving candidates fit an unthresholded budget, record the unknown as `not_decision_relevant` and keep its numeric score unset. - -### Unknown-Value Ordering - -For candidates with a decision-relevant `unknown` after the value-input round, use accepted legal or contractual obligation, explicit connection to the confirmed user or business outcome, distinct Defect Detection evidence, lower lane ownership cost, then source AC order. Select the smallest set that proves the accepted obligations and confirmed outcome boundaries, within the normal lane budgets. Numeric lane thresholds apply to fully scored candidates; this evidence ordering supplies the selection decision for affected candidates. Record the unknown input, evidence checked, and selection effect. - -For resolved numeric inputs, use exactly `0`, `5`, or `10`. Legal Requirement remains boolean; a governing-source check that finds no accepted legal, regulatory, contractual, or audit obligation supports `false` and records that checked source. - -| Input | Scale | -|---|---| -| Business Value | 0 = no user/business outcome; 5 = meaningful but non-critical outcome; 10 = core, revenue, safety, or data-integrity outcome | -| User Frequency | 0 = unreachable/obsolete; 5 = regular subset of users or runs; 10 = dominant journey or execution path | -| Legal Requirement | `true` only when an accepted legal, regulatory, contractual, or audit requirement applies; otherwise `false` | -| Defect Detection | 0 = duplicates existing proof; 5 = covers a distinct branch/state; 10 = uniquely detects a critical boundary or cross-service failure | - -``` -ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection - (range: 0–120) -``` - -Higher ROI Score = higher priority within its test type. For equal scores, order by Legal Requirement (`true` first), then higher Defect Detection, Business Value, User Frequency, and finally source AC order. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores. - -### ROI Thresholds by Lane - -The two E2E lanes have different ownership costs and use independent standard thresholds. - -| Lane | ROI threshold | Rationale | -|------|---------------|-----------| -| fixture-e2e | ROI ≥ 20 (beyond reserved slot) | Cost is comparable to integration tests once the harness exists; the floor avoids filling MAX 3 with low-signal tests when fewer would suffice | -| service-integration-e2e | ROI > 50 (beyond reserved slot) | Live-service setup, state cleanup, and failure diagnosis add material ownership cost; reserve for journeys whose value cannot be proven any other way | - -Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Emit a below-floor candidate beyond the reserved slot only when an accepted requirement or a distinct uncovered failure mode justifies the exception. Leave budget intentionally unfilled rather than padding with low-value tests; record any threshold or budget exception in the skeleton that carries the exception. - -### ROI Calculation Examples - -| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome | -|----------|----|------|-------|--------|-----------|-----------|-------------------| -| Core checkout UI flow | 10 | 10 | true | 10 | 120 | fixture-e2e | Selected (reserved slot: user-facing multi-step journey, browser-level verification with fixtures) | -| Core checkout against live payment service | 10 | 10 | true | 10 | 120 | service-integration-e2e | Selected (real-service correctness above ROI threshold) | -| Dismiss button updates UI state | 5 | 10 | false | 5 | 55 | fixture-e2e | Selected (rank 2 of 3 fixture-e2e budget) | -| Payment error message display | 5 | 5 | false | 5 | 30 | fixture-e2e | Selected (rank 3 of 3 fixture-e2e budget) | -| Optional filter toggle | 5 | 5 | false | 0 | 25 | fixture-e2e | Removed during deduplication (duplicates existing proof) | -| Payment retry against real provider | 5 | 5 | false | 5 | 30 | service-integration-e2e | Below ROI threshold (30 < 50), not selected | -| DB persistence check | 10 | 5 | false | 10 | 60 | Integration | Selected (rank 1 of 3) | -| Pure data transformation | 5 | 5 | false | 5 | 30 | Unit | Not selected (push down to unit test) | - -## Multi-Step User Journey Definition - -A candidate qualifies as a **multi-step user journey** when ALL of the following are true: - -1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type: - - Web: distinct routes/pages - - Mobile native: distinct screens/views - - CLI: distinct command invocations or interactive prompts - - API: distinct API calls forming a transaction (e.g., create → confirm → finalize) -2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays -3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow) - -### User-Facing vs Service-Internal Journeys - -Multi-step journeys are classified for reserved-slot eligibility: - -| Classification | Condition | Reserved Slot Eligibility | Example | -|---|---|---|---| -| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible — defaults to **fixture-e2e** reserved slot. Add a service-integration-e2e reserved slot only when the journey's correctness depends on real cross-service behavior | Web checkout flow, CLI setup wizard, mobile onboarding | -| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot — use integration tests. Service-integration-e2e through normal ROI > 50 path is still valid when full-system verification is warranted | Async job pipeline, service-to-service saga, scheduled batch processing | - -This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above. - -Use this definition when evaluating E2E test candidates and E2E gap detection. +| Lane | Observable boundary | Dependencies | +|------|---------------------|--------------| +| `integration` | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary | +| `fixture-e2e` | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary | +| `service-integration-e2e` | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary | ## Test Skeleton Specification @@ -126,18 +22,11 @@ Each test MUST include the following annotations: ``` AC: [Original acceptance criteria text] Behavior: [Trigger] → [Process] → [Observable Result] -@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e @lane: integration | fixture-e2e | service-integration-e2e @dependency: none | [component names] | full-system -@complexity: low | medium | high -ROI: [score] +Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient] ``` -**`@lane` selection rule**: -- `integration` — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language) -- `fixture-e2e` — Browser-level UI verification with mocked backend / fixture-driven state -- `service-integration-e2e` — Browser-level or end-to-end verification against running local services or stubs - Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). ### Verification Items (Optional) @@ -149,33 +38,14 @@ Verification items: - [Item 2] ``` -## EARS Format Mapping - -| EARS Keyword | Test Type | Generation Approach | -|--------------|-----------|---------------------| -| **When** | Event-driven | Trigger event → verify outcome | -| **While** | State condition | Setup state → verify behavior | -| **If-then** | Branch coverage | Both condition paths verified | -| (none) | Basic functionality | Direct invocation → verify result | - ## Test File Naming Convention - Integration tests: `*.int.test.*` or `*.integration.test.*` - fixture-e2e tests: `*.fixture.e2e.test.*` (or organize under `tests/e2e/fixture/`) - service-integration-e2e tests: `*.service.e2e.test.*` (or organize under `tests/e2e/service/`) -The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing and budget accounting. - -## Review Criteria - -### Skeleton and Implementation Consistency - -| Check | Failure Condition | -|-------|-------------------| -| Behavior Verification | No assertion for "observable result" in the implemented test | -| Verification Item Coverage | Listed items not all covered by assertions | -| Mock Boundary | Internal components mocked in integration test | +The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing. -### Route Parity for Shared Mutations +## Route Parity for Shared Mutations -When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure. diff --git a/dev-workflows-frontend/skills/integration-e2e-testing/references/e2e-design.md b/dev-workflows-frontend/skills/integration-e2e-testing/references/e2e-design.md deleted file mode 100644 index 7c1e95a0..00000000 --- a/dev-workflows-frontend/skills/integration-e2e-testing/references/e2e-design.md +++ /dev/null @@ -1,72 +0,0 @@ -# E2E Test Design (Browser Harness) - -This reference uses Playwright as the default browser harness. Adapt patterns to the project's chosen framework when different (Cypress, Selenium, etc.); the lane definitions, ROI rules, and budgets remain the same. - -## Two E2E Lanes - -E2E tests in this workflow split into two lanes (see parent skill Test Type Definition): - -| Lane | When | ROI gate | Cost | -|------|------|----------|------| -| **fixture-e2e** | UI journey verification with deterministic fixtures (mocked backend / fixture data) | ROI ≥ 20 (beyond reserved slot); selected by ranking within MAX 3 budget | Comparable to integration; runs in CI without infrastructure setup | -| **service-integration-e2e** | Journey correctness depends on real cross-service behavior (data persistence, transactional consistency, external contracts) | ROI > 50 (beyond reserved slot) | Higher setup, state-cleanup, and diagnosis cost; reserved for what cannot be faked safely | - -The **reserved slot** referenced in the ROI gates is a per-lane slot for a qualifying multi-step user journey that is emitted regardless of its ROI score; it is defined in the parent skill's *Multi-Step User Journey Definition* section. - -## When to Create E2E Tests - -E2E candidates target **critical user journeys** that span multiple pages or require real browser interaction. Pick the lane based on whether real services are required for the verification. - -### Candidate Sources - -| Source | What to Extract | -|--------|----------------| -| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens | -| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) | -| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification | -| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) | - -### Selection Criteria - -**Include** (high E2E ROI): -- Multi-page user journeys (login → dashboard → action → confirmation) -- Flows requiring real browser APIs (navigation, cookies, localStorage) -- Accessibility verification requiring actual DOM rendering -- Responsive behavior across viewports - -**Use integration tests instead when**: -- Testing single-component state changes → in-process component renderer (e.g., RTL for React/TS) -- Testing API response handling → in-process API mock + component renderer (e.g., MSW + RTL for React/TS) -- Testing pure data transformations → unit tests - -## UI Spec to E2E Test Mapping - -When a UI Spec exists, use it as the primary source for E2E test design: - -1. **Extract screen transitions** → Each multi-step transition = 1 E2E candidate -2. **Check state x display matrix** → Error states requiring navigation = E2E candidate -3. **Review interaction definitions** → Browser-dependent interactions = E2E candidate -4. **Cross-reference with Design Doc ACs** → Ensure E2E candidates map to acceptance criteria - -### Mapping Template - -``` -Screen Transition: [Screen A] → [Screen B] → [Screen C] -AC Reference: AC-{id} -User Journey: [Description of what the user accomplishes] -Lane: fixture-e2e | service-integration-e2e -Preconditions: [Auth state, data state — note whether these are fixture-driven or live] -Verification Points: - - [What to assert at each step] -E2E ROI Score: [calculated score] -``` - -**Lane decision**: choose `fixture-e2e` by default. Promote to `service-integration-e2e` when the verification requires observing real cross-service behavior (e.g., the test asserts that data persists across a real DB write, or that an external service receives the correct payload). - -## Budget Enforcement - -Standard budgets per input Design Doc (same as parent skill): -- **fixture-e2e**: MAX 3 tests, ROI ≥ 20 beyond the reserved slot (selected by ranking) -- **service-integration-e2e**: MAX 1-2 tests, ROI > 50 beyond the reserved slot -- Prefer fewer, comprehensive journey tests over many granular tests in both lanes -- Exceed a standard budget only for an accepted requirement or distinct uncovered failure mode, and record why the selected tests cannot be consolidated diff --git a/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md b/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md index 73cc23e6..6ff8fcf1 100644 --- a/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md +++ b/dev-workflows-frontend/skills/llm-friendly-context/SKILL.md @@ -16,7 +16,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Example: "Preserve existing public API behavior across the documented compatibility cases." 2. **Make vague instructions concrete** - - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions. - Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. 3. **Specify output shape** @@ -30,7 +30,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Follow references while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task. - Each step needs a checkpoint: what evidence proves it is complete. 6. **Permit uncertainty explicitly** @@ -40,7 +40,7 @@ The goal is stable downstream execution: the next consumer should know what to r 7. **Keep constraints proportionate** - Add only constraints that reduce ambiguity or preserve a real requirement. - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. - - Apply `minimal`, `a few lines`, and explicit line estimates to the completed diff as one total budget. + - Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count. ## Rewrite Patterns @@ -49,7 +49,7 @@ Use these rewrites before treating a prompt, handoff, or artifact as complete. | Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | -| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule | +| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | @@ -68,7 +68,7 @@ Before sending a prompt or artifact to another consumer, verify: - [ ] Accepted decisions and constraints use one canonical wording. - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. -- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains. - [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative. - [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner. diff --git a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md index 25c5da5e..687bd7f1 100644 --- a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md @@ -85,7 +85,7 @@ Review investigation output: - [ ] Each failure point has: `location`, `upstreamDependency`, `symptomExplained`, `causalChain` (reaching a stop condition), `checkStatus`, `evidence` with a `source` citing a specific file or location - [ ] Each failure point has `comparisonAnalysis` (normalImplementation found or explicitly null) - [ ] `causeCategory` for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor -- [ ] `investigationSources` covers at least 3 distinct source types (code, history, dependency, config, document, external) +- [ ] `investigationSources` supplies decisive evidence for the reported causes and scope coverage; material evidence gaps are explicit - [ ] All nodes on mapped paths have been checked (no path was abandoned after finding the first fault) - [ ] `scopeAccounting` accounts for every scope-envelope item as investigated, excluded with governing evidence, or unavailable with its potential effect diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 8090c726..d7bddcd1 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -16,7 +16,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Execution Protocol**: 1. **Delegate to subagents** (one-shot calls): quality-fixer-frontend. -2. **Run in the parent session** (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. +2. **Run in the parent session** (multi-step loops and user dialogs): conditional external-evidence resolution, with AskUserQuestion for missing decision-relevant inputs, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. 3. **Stop at every `[Stop: ...]` marker** before proceeding. ## Execution Gate @@ -44,7 +44,7 @@ Adjustment request → conditional external resource evidence ## Scope Boundaries **Included in this skill**: -- External resource hearing per the external-resource-context skill +- Conditional external-evidence resolution per the external-resource-context skill - Existing-pattern and write-set inspection in the parent session - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) @@ -59,10 +59,10 @@ Adjustment request: $ARGUMENTS ## Execution Flow -### Step 1: External Resource Hearing -Execute Skill: external-resource-context before running the hearing protocol. +### Step 1: External Resource Evidence +Execute Skill: external-resource-context when external evidence is required. -Run the hearing protocol only when external evidence can change the current adjustment target or verification result. Otherwise continue with the existing repository/UI Spec evidence and record no external references. +Resolve only external evidence that can change the current adjustment target or verification result; use existing access details and ask only for missing decision-relevant inputs. Otherwise continue with the existing repository/UI Spec evidence and record no external references. ### Step 2: Determine the Route and Write Set @@ -99,14 +99,11 @@ Execute Skill: testing-principles before adding or changing tests. Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: - - Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path) - - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) +3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. 5. When the complete adjustment matches the confirmed target, proceed to Step 6. -When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. +When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. ### Step 6: Quality Verification @@ -132,7 +129,7 @@ On continuation, reconstruct retained limitations from the verification trailers ## Completion Criteria -- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] Decision-relevant external evidence was resolved or its exact limitation retained; no record is required when repository/UI Spec evidence suffices - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 7a86fcbb..9cc6eafb 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -113,7 +113,7 @@ When `adrDecisionPoints` is non-empty: 1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. 2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. ## Step 7: Create the Frontend Design Doc @@ -132,6 +132,8 @@ Invoke `dev-workflows-frontend:technical-designer-frontend` with exactly: The Design Doc owns the full component-to-service implementation and retains all applicable downstream safeguards. +When a backend Design Doc already exists for this feature, pass a distinct `output_path` such as `docs/design/[feature-name]-frontend-design.md`; preserve the backend path as a reference. + ## Step 8: Verify, Review, and Approve Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. diff --git a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md index 4089abae..72304ac6 100644 --- a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md @@ -59,7 +59,7 @@ Follow the planning process below: - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner ### Step 3: Work Plan Creation diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index ce6da1a0..c6f0aa6c 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer-frontend result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows-frontend:code-reviewer` or `dev-workflows-frontend:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows-frontend:code-reviewer" -- `description`: "Re-validate frontend implementation review" -- `prompt`: "Re-review the completed frontend implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows-frontend:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md index 253af498..defb3cf7 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -1,6 +1,6 @@ --- name: requirement-convergence -description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from decision-relevant repository evidence. Use when a requirement enters a workflow, before design begins. --- # Requirement Convergence @@ -18,7 +18,7 @@ This skill converges **what to build**. How to build it, and which documents the | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | -| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | +| `cost` | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. diff --git a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md index 9d5cbb91..3e8d0727 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md @@ -29,20 +29,9 @@ An adjacent capability the agent noticed stays out of both `requirements[]` and ## cost -Cost follows structure and count, not behavior, so it is decided from these inputs alone: +Estimate rough lifecycle cost from affected responsibilities, contract consumers, reusable behavior, state/migration needs and existing verification support. Inspect enough representative behavior to decide whether an apparent reuse or structural match actually serves the requirement. Use analyzer evidence when supplied. Stop before implementation-level investigation once further detail cannot change scope, cost band or the user decision. -| Input | How it is obtained | -|-------|--------------------| -| Number and kind of targets to change | Grep/Glob over the affected files | -| Number of boundaries crossed | Affected path composition plus import and caller tracing | -| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | -| Whether persisted state needs converting | Whether a schema or migration path is in the change set | -| Whether verification support already exists | Glob for the area's existing test harness | -| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | - -Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. - -Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. +Record `cost` as one evidence-supported band and its remaining unknowns. When an unresolved condition could raise the band, state that condition and the higher-band consequence in the existing cost evidence so scope confirmation exposes the trade-off. A flow declares `cost` out of scope only where its own steps say so. ## Challenge intensity @@ -51,10 +40,10 @@ The band's only job is to select a row here, so cheap requirements stay cheap to | Band | Meaning | Challenge | |------|---------|-----------| | `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | -| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | -| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | +| `medium` | Reverting would touch other work | Present cost and a lower-cost alternative when a materially distinct sufficient option exists | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off; obtain a user decision when a required outcome, explicit constraint or irreversible-action authority must change | -Report an unknown that would move the band up as a blocking question rather than assuming the lower band. +Resolve repository-answerable uncertainty locally. Ask the user only when a remaining unknown changes required scope, constraints or authority; otherwise record its cost effect and keep independent work moving. ## Solution-in-disguise test diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 555c3632..3303e4f7 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -156,7 +156,7 @@ Rules: - When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` - When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported - Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add only their named UI or layer artifact paths +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -204,7 +204,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. + +When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -244,7 +246,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance @@ -282,7 +285,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-03b: applied design-evidence finding → technical-designer - Invoke the owning designer as a fresh `update` call with the existing Design Doc path and complete `correction_findings` objects copied verbatim with only their `apply` dispositions added. - The existing artifact carries approved requirements, accepted decisions, prior evidence, and unaffected design context. Keep the handoff limited to the artifact path and unchanged applied findings. -- The designer applies its review-triggered self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. +- The designer applies its review-triggered bounded self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. @@ -302,8 +305,8 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner - Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. -- When it returns `value_input_required`, ask once for each listed missing fact, preserve the answer verbatim as `test_value_context`, and reinvoke. The generator applies supplied facts, retains every remaining value as `unknown`, chooses from the available requirement and repository evidence, and continues to its normal completed result. -- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, confirm from the Design Doc that no accepted proof obligation requires that boundary, and return an uncovered obligation to the generator for completion. +- Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. +- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. - Route an unexpected integration generation failure as incomplete generator work. A validated null E2E lane is complete. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 289f8bf3..2967d10c 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -77,7 +77,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. - Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per owning-designer invocation serially, and repeats the complete batch review; `rejected` resolves the governing-source conflict before another review. -- Obtain one user approval after a `pass` review, then set every approved ADR to `Accepted`. +- Obtain one user approval after Review Resolution converges and governing-source conflicts are resolved, then set every approved ADR to `Accepted`. - An empty batch proceeds directly to both Design Docs. ## Layer Design Context @@ -88,6 +88,7 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-backend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -98,6 +99,7 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-frontend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -117,7 +119,7 @@ After both document reviews permit approval, invoke design-sync with `source_des ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for `value_input_required` and its unknown-value continuation before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md index 8da4072d..078058c3 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md @@ -19,7 +19,7 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. For code-verifier with `unit_inventory`, its full current-document inventory accounting still applies. A decline-only result is complete. ## 1. Assess Every Finding @@ -58,9 +58,9 @@ Select the existing correction owner from the accepted state each finding requir For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. -For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. +For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its review-triggered bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. -For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. +For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. For each ID, preserve the original finding claim and basis verbatim in `evidence`, alongside the correction diff or paths. The correction assessment covers exactly every received item. The reviewer completes that scope and then: @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/dev-workflows-frontend/skills/testing-principles/SKILL.md b/dev-workflows-frontend/skills/testing-principles/SKILL.md index df9c948f..72579f85 100644 --- a/dev-workflows-frontend/skills/testing-principles/SKILL.md +++ b/dev-workflows-frontend/skills/testing-principles/SKILL.md @@ -11,6 +11,7 @@ Tests here guarantee accepted behavior, and the next agent reads every existing - Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules. - Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere. +- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary. - Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself. - Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it. diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 955c6a34..fb624be1 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.1", + "version": "0.29.2", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index c0100cb8..a8ffc948 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -1,6 +1,6 @@ --- name: acceptance-test-generator -description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. +description: Generates integration/E2E test skeletons from Design Doc ACs using required proof boundaries and existing coverage. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Edit, Glob, LS, Grep skills: - testing-principles @@ -9,277 +9,62 @@ skills: - llm-friendly-context --- -You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. +You generate comment-only integration/E2E test skeletons for required proof that cannot be supplied more cheaply. Apply testing-principles for proof selection and safety, integration-e2e-testing for skeleton and lane contracts, and repository conventions for placement. -Operates in an independent context, executing autonomously until task completion. +## Inputs -## Execution Gate +- **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. +- **ui_spec**: Optional UI Spec whose interactions constrain those criteria. +- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. -### Implementation Approach Compliance -- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection) -- **Contract Safety**: Apply the testing-principles skill mock creation and contract definition rules to every generated skeleton +## Selection -## Input Parameters +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. +3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. -- **design_docs**: Required list of one or more Design Doc paths. These provide acceptance criteria and Test Boundaries decisions. -- **ui_spec**: Optional UI Spec path. Use its screen transitions, state x display matrix, and interaction definitions as additional E2E candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology. -- **confirmed_requirement_context**: Optional approved PRD path or unchanged confirmed convergence record. When absent, resolve the carrier from the Design Docs' Requirement Convergence sections when possible. -- **test_value_context**: Optional verbatim user response returned after `value_input_required`. Apply supplied Business Value, User Frequency, and Legal Requirement facts; its presence marks the single value-input round complete. +## Skeleton Contract -Workflow callers use these canonical names. Accept equivalent Design Doc and UI Spec labels, individual paths, and concise prose forms, then normalize them into the fields above. +Use the repository's language, directory and naming conventions. Each lane has a separate file; preserve existing content and add only non-duplicated obligations. Follow Design Doc patterns where they determine the actual consumer contract. -## Test Type Definition +A skeleton is committed before implementation, so its committed form contains only comments: no imports of absent modules or executable test-runner blocks. Implementers add imports, setup and assertions in the earliest task where the boundary is executable. Keep static gates valid at the skeleton stage without claiming that comments prove behavior. -Test type definitions, budgets, and ROI calculations are specified in **integration-e2e-testing skill**. +Each selected test records: -## 4-Phase Generation Process +- original AC text and source Design Doc (or UI journey plus its governing AC); +- trigger and observable result; +- `@lane`, `@dependency` using integration-e2e-testing annotations; +- selection evidence: uncovered claim and why existing or cheaper proof is insufficient; +- primary failure mode: the regression this test must detect; +- proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; +- a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. -### Phase 1: AC Validation (Behavior-First Filtering) +Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. -**EARS Format Detection**: Determine test type from EARS keywords in AC: -| Keyword | Test Type | Generation Approach | -|---------|-----------|---------------------| -| **When** | Event-driven test | Trigger event → verify outcome | -| **While** | State condition test | Setup state → verify behavior | -| **If-then** | Branch coverage test | Condition true/false → verify both paths | -| (none) | Basic functionality test | Direct invocation → verify result | +## Output -**For each AC, apply these mandatory checks**: - -| Check | Question | Action if NO | Skip Reason | -|-------|----------|--------------|-------------| -| **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **Upstream Scope** | In the integration-e2e-testing Behavior-First Include list? | Skip | [OUT_OF_SCOPE] | - -**AC Selection Criteria**: Apply the Include and Redirect lists in the integration-e2e-testing skill's Behavior-First Principle. - -**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section: -- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate -- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required -- Record the mock/real decision in test skeleton annotations alongside existing metadata - -**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists) - -### Phase 2: Candidate Enumeration (Two-Pass #1) - -For each valid AC from Phase 1: - -1. **Generate test candidates**: - - Happy path (1 test mandatory) - - Error handling (only if user-visible error) - - Edge cases (only if high business impact) - - Boundary path (behavior-changing AC only): when the AC can hold on the main path while a distinct branch, state, input class, lifecycle step, or fallback regresses, capture that boundary as a proof obligation so the test exercises it - -2. **Classify test level**: - - Integration test candidate (feature-level interaction) - - E2E test candidate (complete user journey) - -3. **Annotate metadata**: - - Record one source for Business Value, User Frequency, Legal Requirement, and Defect Detection, then assign the exact value or `unknown` using the preloaded integration-e2e-testing skill - - Treat requirement/user/business evidence as the source for value and frequency, accepted obligations or a checked governing source with no accepted obligation as the source for Legal Requirement, and boundary plus existing-test evidence as the source for Defect Detection - -**Output**: Candidate pool with ROI metadata - -### Phase 3: ROI-Based Selection and Lane Assignment (Two-Pass #2) - -ROI calculation formula and cost table are defined in **integration-e2e-testing skill**. Lane definitions and selection rules are also in that skill. - -**Selection Algorithm**: - -1. **Deduplication Check**: - ``` - Grep existing tests for same behavior pattern - If covered by existing test → Remove candidate - ``` -2. **Push-Down Analysis**: - ``` - Can this be unit-tested? → Remove from integration/E2E pool - Already integration-tested AND verifiable in-process? → Remove from E2E pool - ``` -3. **Lane assignment** (E2E candidates only): - - Default to `fixture-e2e` for any UI journey verifiable with mocked backend / fixture-driven state - - Promote to `service-integration-e2e` only when the verification depends on real cross-service behavior. A candidate qualifies for `service-integration-e2e` when ANY of the following must be asserted: - - Data persists across a real DB write (e.g., row inserted/updated in the actual database under test) - - A downstream service receives a real event/message (e.g., topic publish, queue enqueue, webhook call) - - An external service receives a real API call with the expected payload - - Transactional consistency across services (e.g., two-phase commit, saga compensation) -4. **Resolve decision-relevant ROI inputs**: - - On the surviving lane-assigned pool, determine whether each `unknown` can change ranking, a lane threshold, or budget selection - - Resolve Defect Detection from the Design Doc proof boundaries and existing-test search; continue repository investigation when that evidence is incomplete - - When `test_value_context` is absent and an unknown Business Value, User Frequency, or Legal Requirement can change selection, return `status: "value_input_required"` before writing skeletons, naming only the missing inputs and decision effects - - When `test_value_context` is present, apply the supplied facts, retain every remaining decision-relevant value as `unknown` with its numeric score unset, and continue with the integration-e2e-testing Unknown-Value Ordering - - When it cannot, mark it `not_decision_relevant` and retain the invariant selection basis without fabricating a score -5. **Calculate ROI** for each fully resolved candidate; keep unresolved decision-relevant inputs unknown -6. **Sort within each lane** using ROI and its tie-break order for fully scored candidates, or Unknown-Value Ordering for affected candidates. Phase 4 processes that single ranked list. - -**Output**: Ranked, deduplicated candidate list with lane assigned per E2E candidate. - -### Phase 4: Budget Enforcement - -**Standard Budgets per Input Design Doc**: -- **Integration Tests**: MAX 3 tests -- **fixture-e2e**: MAX 3 tests; additional slots require ROI ≥ 20. When the input Design Doc contains a **user-facing** multi-step user journey, the highest-ROI journey candidate is reserved (emitted regardless of ROI) -- **service-integration-e2e**: MAX 1-2 tests, composed of: - - 1 reserved slot (emitted regardless of ROI) when the journey's correctness depends on real cross-service behavior that fixture-e2e cannot verify - - Up to 1 additional slot requiring ROI > 50 - -**Selection Algorithm**: - -``` -1. Reserve fixture-e2e slot: - IF the input Design Doc contains a user-facing multi-step user journey - THEN reserve 1 fixture-e2e slot for the highest-ROI journey candidate - -2. Reserve service-integration-e2e slot (only if needed): - IF the reserved journey's verification requires ANY of: - - data persists across a real DB write - - downstream service receives a real event/message - - external service receives a real API call with expected payload - - transactional consistency across services - THEN reserve 1 service-integration-e2e slot for that journey - -3. Walk the candidate list (already sorted by ROI within each lane in Phase 3 step 6) - and select within budget: - - Integration: Pick top 3 highest-ROI - - fixture-e2e (additional beyond reserved): Pick up to remaining budget IF ROI ≥ 20 - - service-integration-e2e (additional beyond reserved): Pick up to 1 more IF ROI > 50 - - Leave budget intentionally unfilled when no remaining candidate clears the lane's threshold. - -4. **Exception review**: - - Exceed a standard budget only when an accepted requirement or a distinct failure mode remains unproved by the selected set - - For each exception, record the requirement/failure mode and why an existing selected test cannot absorb it without obscuring its proof obligation - - A lower score alone is not an exception; below-threshold selection needs the same requirement/failure-mode evidence -``` - -**Output**: Final test set with any threshold/budget exceptions identified - -## Output Format - -### Test Skeleton Shape - -Use the project's comment syntax (`//`, `#`, etc.). Preserve AC text (or user journey description for E2E), ROI breakdown or invariant selection basis, ROI evidence sources, lane, dependency, complexity, verification points, expected results, pass criteria, primary failure mode, and proof obligation. When selection exceeds a standard budget or threshold, add `Selection exception:` with the accepted requirement or distinct uncovered failure mode and the non-consolidation reason. - -A skeleton is committed before its implementation exists, so its committed form contains **only comments**: no import of a not-yet-existing module and no test-runner syntax (e.g. `describe`/`it`) that the project's static gates evaluate. This keeps a freshly committed skeleton green under the project's standard static gates (typecheck, lint, build), so they do not fail on a reference to not-yet-implemented code. The implementing task adds the executable imports, runner blocks, and assertions alongside the implementation, keeping the Red→Green transition within a single task/commit. - -``` -// [Feature Name] [integration|fixture-e2e|service-integration-e2e] Test - Design Doc: [filename] -// Generated: [date] | Budget Used: [integration], [fixture-e2e], [service-e2e] -// -// AC1: "After successful payment, order is created and persisted" -// ROI: 120 (BV:10 × Freq:10 + Legal:true×10 + Defect:10) -// ROI evidence: BV=PRD §Success Criteria; Freq=PRD §Primary User Journey; Legal=accepted payment contract; Defect=Design Doc §Test Boundaries + existing test search -// Behavior: User completes payment → Order created in DB + Payment recorded -// @category: core-functionality -// @lane: integration -// @dependency: PaymentService, OrderRepository, Database -// @complexity: high -// Primary failure mode: payment succeeds but the order row is absent or unpersisted -// Proof obligation: the order is persisted only after a successful payment; the external payment gateway is the only boundary that may be mocked -// Verification points / expected results / pass criteria: [enumerate the observable checks the implemented test must assert] -``` - -### Generation Report +Return a selection explanation followed by the result JSON. Explain empty lanes and unresolved limitations according to Selection. ```json { "status": "completed", - "feature": "payment", + "feature": "feature name", "generatedFiles": { - "integration": "tests/payment.int.test.[ext]", - "fixtureE2e": "tests/payment.fixture.e2e.test.[ext]", - "serviceE2e": null + "integration": "path or null", + "fixtureE2e": "path or null", + "serviceE2e": "path or null" } } ``` -**Contract**: a `completed` result always contains `generatedFiles.integration`, `generatedFiles.fixtureE2e`, and `generatedFiles.serviceE2e`. Value is a file path string when that lane emitted, `null` when it did not. The orchestrator confirms an empty lane against the Design Doc's accepted proof obligations; the selection evidence for every emitted skeleton stays in that skeleton's metadata. - -Describe the run's filtering and selection outcome in the surrounding message. Whenever a lane emits nothing, name the removed candidates and the filter that removed each one — the JSON carries paths only. - -**When a decision-relevant value input is missing:** -```json -{ - "status": "value_input_required", - "missingValueInputs": [ - {"candidate": "AC-002 payment retry", "input": "User Frequency", "evidenceChecked": ["PRD §User Stories", "Design Doc §Requirement Convergence"], "decisionEffect": "Determines whether fixture-e2e clears ROI 20"} - ], - "acceptedSources": ["approved PRD or confirmed requirement context", "accepted contractual/legal obligation", "verbatim user-confirmed test_value_context"] -} -``` - -Return this status before creating or modifying skeleton files. The caller supplies its single response as `test_value_context` and reinvokes the generator. Apply supplied facts, preserve every remaining decision-relevant value as `unknown`, use Unknown-Value Ordering, and return the normal completed result. Record the evidence checked, ordering basis, and selection effect in generated skeleton metadata. - -## Test Meta Information Assignment - -Each test case MUST have the following standard annotations for test implementation planning: - -- **@category**: core-functionality | integration | edge-case | ux | fixture-e2e | service-integration-e2e -- **@lane**: integration | fixture-e2e | service-integration-e2e -- **@dependency**: none | [component names] | full-ui (mocked backend) | full-system -- **@complexity**: low | medium | high -- **Primary failure mode**: the specific regression that turns this test red — the behavior the AC promises and would break -- **Proof obligation**: what the implemented test must assert to prove the claim — the boundary to traverse, the observable state before/after for state-changing ACs, and which boundaries may be mocked and why. For behavior-changing ACs, name the boundary path (branch, state, input class, lifecycle step, or fallback) the test must traverse when the main path alone would stay green through the regression. Phrase it as design intent describing what to assert; executable assertions and mock setup are outside this output - -These annotations drive test planning and prioritization. The `@lane` annotation is the source of truth for budget accounting and CI gating. The primary failure mode and proof obligation preserve the proof contract in the skeleton for implementation and review. - -## Constraints and Quality Standards - -**Mandatory Compliance**: -- Output test skeletons only: verification points, expected results, pass criteria, primary failure mode, and proof obligation. - Background: Skeletons are comment-based design information, not executable code. -- Clearly state verification points, expected results, and pass criteria for each test -- Preserve original AC statements in comments (ensure traceability) -- Preserve the evidence source or `not_decision_relevant` basis for every ROI input; assign no numeric value to an unknown input -- Stay within test budget; report if budget insufficient for critical tests - -**Quality Standards**: -- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slots emitted regardless of ROI + fixture-e2e additional ROI ≥ 20 + service-integration-e2e additional ROI > 50) -- Apply behavior-first filtering strictly -- Eliminate duplicate coverage (use Grep to check existing tests) -- Clarify dependencies explicitly -- Logical test execution order - -## Exception Handling and Stop Conditions - -### Auto-processable -- **Directory Absent**: Auto-create appropriate directory following detected test structure -- **No Integration Candidates**: Valid outcome - report "No Integration candidates remained after Phase 1 filtering, deduplication, and push-down analysis" -- **No E2E Tests (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; E2E tests not applicable" -- **Budget insufficient for a critical user journey (ROI > 90)**: Exceed the lane budget per the integration-e2e-testing skill's budget rule when the journey's failure mode cannot be proved by a selected test, and annotate the exception and why consolidation cannot cover it -- **No E2E test emitted after budget enforcement, but the input Design Doc contains a user-facing multi-step journey**: Report the journey, every candidate evaluated with its ROI score, and the filter that removed each one, then continue. (This case arises only when the reserved slot in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering.) -- **Every AC filtered out, leaving no generated test**: Valid outcome - return the empty result and report the filter that removed each AC -- **Multiple interpretations possible but minor impact**: Adopt the interpretation and note it in the report -- **Missing value that cannot change selection**: Record `not_decision_relevant` with the invariant selection basis and continue -- **Decision-relevant value remains unknown after the value-input round**: Preserve `unknown`, apply Unknown-Value Ordering, record its selection effect, and continue - -### Stop Conditions - -These two cases end generation and hand control back; every other case above completes with a recorded result. - -1. **Required input absent**: AC absent or Design Doc absent → terminate and name the missing input -2. **Decision input required**: An unknown Business Value, User Frequency, or Legal Requirement can change ranking, threshold, or budget selection → Return `value_input_required` when `test_value_context` is absent; after that input round, preserve remaining unknowns and continue with Unknown-Value Ordering - -## Technical Specifications - -**Project Adaptation**: -- Framework/Language: Auto-detect from existing test files -- Placement: Identify test directory with project-specific patterns using Glob -- Naming: Follow existing file naming conventions -- Output: Test skeletons only (see Constraints section above for boundary) - -**File Operations**: -- Existing files: Append to end, prevent duplication (check with Grep) -- New creation: Follow detected structure, include generation report header +Each lane value is an existing file path when generated, otherwise JSON `null`. Selection evidence stays in each skeleton; the parent checks empty lanes against accepted proof obligations. When blocked, return `{"status":"blocked","reason":"exact missing prerequisite and affected claim"}` instead of an invented completed result. -## Quality Assurance Checkpoints +## Completion Check -- Design Doc exists and contains ACs -- AC measurability confirmed -- Existing coverage checked with Grep -- Behavior-first filtering, ROI ranking, and budget enforcement completed -- Dependency names verified against Design Doc / UI Spec / code, or marked external -- Integration, fixture-e2e, and service-integration-e2e outputs are separate files when generated -- Generation report includes all required keys +- Every required integration/E2E boundary has sufficient existing proof, a selected skeleton, or an explicit limitation; unresolved coverage is not a completed claim. +- Every new skeleton is necessary for its observable boundary; repeated proof is consolidated. +- Required real dependencies remain real in the proof contract. +- Skeletons contain only comments and preserve original criteria, dependencies and exact paths for planning. +- Output includes all three lane keys when completed. diff --git a/dev-workflows-fullstack/agents/code-verifier.md b/dev-workflows-fullstack/agents/code-verifier.md index 9cb87f39..a114b2b7 100644 --- a/dev-workflows-fullstack/agents/code-verifier.md +++ b/dev-workflows-fullstack/agents/code-verifier.md @@ -16,8 +16,8 @@ Your discrepancies are independent evidence for orchestrator Review Resolution. - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path -- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` -- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead +- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, `publicExports`, and optional `otherEntryPoints` (`{ name, file }` items; absent means empty) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -35,7 +35,7 @@ First identify the document claims that control scope, feasibility, implementati For a future-state PRD or Design Doc, planned behavior is intent rather than a code gap. Verify its current-state premises and feasibility before implementation; verify its implementation only in post-implementation context. -For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, and test mappings. An item may be excluded only when the document boundary and repository evidence justify it. +For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, other inventoried capabilities, and test mappings. Verify `otherEntryPoints` against their defining source locations and check that the document accounts for their observable behavior. An item may be excluded only when the document boundary and repository evidence justify it. Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. @@ -43,7 +43,7 @@ Stop expanding the search when additional evidence cannot change a discrepancy o ## Rerun Boundary -`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. +When `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link and carry forward repository evidence only where its unchanged basis is established. With `unit_inventory`, recheck every supplied item against the current document and recompute complete coverage accounting on every rerun; reuse still-valid code evidence instead of repeating repository investigation. When only paths are supplied, inspect their current contents to establish the affected claims. Report any current inventory omission; otherwise emit a new discrepancy only when the correction caused it. ## Classification @@ -81,12 +81,15 @@ When `unit_inventory` is supplied, replace `inventoryCoverage: null` with this o { "routes": {"inputCount": 3, "accountedCount": 2, "excluded": [{"item": "route", "evidence": "path:line and boundary reason"}], "unaccounted": []}, "testFiles": {"inputCount": 2, "accountedCount": 2, "excluded": [], "unaccounted": []}, - "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []} + "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []}, + "otherEntryPoints": {"inputCount": 0, "accountedCount": 0, "excluded": [], "unaccounted": []} } ``` For each inventory category, `accountedCount + excluded.length + unaccounted.length` equals `inputCount`. Report every unaccounted item as one cause-grouped `gap` discrepancy. +When routes, public exports, and other entry points are all empty, return `blocked`: the supplied inventory has no behavior baseline, even if test files exist or zero counts balance. + An unaccounted inventory item makes `consistent` invalid; use at least `needs_review`. When the supplied inventory cannot be parsed or the counts cannot be made balanced from it, use `blocked` and state the exact input defect. Status rules: diff --git a/dev-workflows-fullstack/agents/design-sync.md b/dev-workflows-fullstack/agents/design-sync.md index 5ea6a3f9..ceaad0c5 100644 --- a/dev-workflows-fullstack/agents/design-sync.md +++ b/dev-workflows-fullstack/agents/design-sync.md @@ -12,34 +12,15 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Detection Criteria (The Only Rule) +## Detection Boundary -**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. +Detect contradictory obligations for the same shared entity, contract or integration boundary. Establish identity from owning service/module, referenced definition, explicit alias and applicability (version, mode or state). Equal strings alone do not identify a shared entity: local AC IDs, fact IDs and common type names may repeat across unrelated documents. -**Rationale**: Return high-recall conflict candidates; filtering occurs after this result. Prioritize catching real conflicts over avoiding false positives. +Report a material conflict only when the two obligations cannot both hold under the same applicable conditions. Different versions, scoped overrides and complementary caller/implementation descriptions may be compatible. Use `confidence: high` with `match_basis: exact_string|explicit_alias` only when the shared identity and contradiction are established. Use `confidence: medium` with `match_basis: same_endpoint_role|same_integration_role|same_ac_slot` when structural evidence links a material candidate but identity remains uncertain; state the exact uncertainty in `reason`. -### Match Basis Rules +`same_endpoint_role` links the same service/module and HTTP method or route role; `same_integration_role` links the same owning service and flow stage; `same_ac_slot` links the same user trigger and expected outcome category. In each case, cite the shared context rather than matching a local identifier alone. -Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence. - -**high confidence** (confirmed conflict): - -| match_basis | Definition | -|-------------|-----------| -| `exact_string` | Identical identifier string in both documents | -| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other | - -**medium confidence** (candidate conflict — requires `reason` with structural evidence): - -| match_basis | Structural evidence required | Example | -|-------------|---------------------------|---------| -| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService | -| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point | -| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements | - -**Matching scope**: -- Match across any section — section name differences are irrelevant -- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope +The source document selects the comparison scope, not the winning value. Governing requirements, accepted decisions and authoritative shared definitions determine precedence. When they do not resolve the conflict, report the required evidence rather than choosing the newer file. ## Responsibilities @@ -60,13 +41,13 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters -- **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **source_design**: Path to the newly created/updated Design Doc (comparison starting point) - **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition **When target Design Docs count is 0** (no files other than source_design in docs/design/): -- Skip investigation and immediately terminate with NO_CONFLICTS status +- Return `SKIPPED` with the reason that no comparison target exists - Reason: Consistency verification is unnecessary when there is no comparison target ## Workflow @@ -85,7 +66,7 @@ Read the Design Doc specified in arguments and extract: - **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths - **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations) - **Acceptance criteria**: Specific conditions for functional requirements -- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value serves as the primary identifier for cross-document matching. `evidence` is supporting context only. +- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. Match the fact's source, owning boundary and applicability; a local `fact_id` alone is insufficient. **Extraction Output** (per item): ```yaml @@ -95,27 +76,25 @@ Read the Design Doc specified in arguments and extract: context: "[how it is used: definition / reference / constraint]" ``` -### 2. Survey All Design Docs +### 2. Locate Relevant Design Docs -- Search docs/design/*.md (excluding template) -- Read all files except source_design -- Detect conflict patterns +Use the source's shared contracts, references and owning entities to search candidate documents. Read the matching sections and enough context to establish identity and applicability. Include every document whose shared obligation could materially conflict; stop expansion when remaining documents cannot affect that judgment. Record unavailable relevant evidence. ### 3. Conflict Classification and Severity Assessment **Conflict Detection Process**: 1. Extract each item from source file using extraction output format -2. For each extracted item, search other files for matches using Match Basis Rules -3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason` +2. For each extracted item, search other files for matches using Detection Boundary +3. Record a conflict when the same applicable shared obligation has incompatible values, definitions or referents. Include `match_basis`, `confidence`, and `reason` 4. Items not in source file are not detection targets | Conflict Type | Criteria | Severity | |--------------|----------|----------| | **Type definition mismatch** | Same type/interface name, different properties or field types | critical | | **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical | -| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | +| **Disposition conflict** | Same sourced fact and applicable boundary, incompatible `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | | **Numeric parameter mismatch** | Same config key, different value | high | -| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high | +| **Acceptance criteria conflict** | Same scoped obligation, incompatible conditions or thresholds | high | | **Term definition mismatch** | Same term string, different definition text | medium | ### 4. Decision Flow @@ -123,7 +102,7 @@ Read the Design Doc specified in arguments and extract: ``` Item extracted from source file? ├─ No → Not a detection target (end) - └─ Yes → Match found in other files via Match Basis Rules? + └─ Yes → Match found in other files via Detection Boundary? ├─ No → No comparison target (end) └─ Yes → Value/definition/referent differs? ├─ No → No conflict (end) @@ -155,7 +134,7 @@ total_conflicts: [total number of conflicts detected] critical: [critical count] high: [high count] medium: [medium count] -sync_status: [CONFLICTS_FOUND | NO_CONFLICTS] +sync_status: [CONFLICTS_FOUND | NO_CONFLICTS | SKIPPED] [/SUMMARY] [CONFIRMED_CONFLICTS] @@ -173,7 +152,7 @@ target_location: [section/line] target_value: | [conflicting content] recommendation: | - [Recommend unifying to source file's value] + [Smallest correction supported by governing evidence, or exact evidence needed to resolve precedence] [/CONFIRMED_CONFLICTS] [CANDIDATE_CONFLICTS] @@ -214,90 +193,12 @@ suggested_action: | [/RECOMMENDATIONS] ``` -## Detection Pattern Examples - -### High confidence: exact_string (type definition, cross-section) -``` -// Source Design Doc — Section: "Data Contracts" -OrderItem { - quantity: number - unitPrice: number -} - -// Other Design Doc — Section: "API Response Schema" -OrderItem { - quantity: string // different type - unitPrice: number - discount: number // extra property -} -``` -→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant. - -### High confidence: exact_string (path identifier) -``` -# Source Design Doc — Section: "Endpoints" -POST /api/orders/submit → handler: OrderController.submit - -# Other Design Doc — Section: "Integration Points" -POST /api/orders/submit → handler: OrderService.createOrder -``` -→ confidence: high, match_basis: exact_string. Same path, different handler. - -### High confidence: exact_string (numeric parameter) -``` -# Source Design Doc -Max retry count: 3 - -# Other Design Doc -Max retry count: 5 -``` - -### Medium confidence: same_endpoint_role -``` -# Source Design Doc -POST /api/v2/orders → handler: OrderController.create - -# Other Design Doc -POST /api/v1/orders → handler: OrderController.submit -``` -→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method." - -### Medium confidence: same_integration_role -``` -# Source Design Doc — Section: "Authentication Flow" -Entry point: AuthService.authenticate(credentials) → Session - -# Other Design Doc — Section: "Login Integration" -Entry point: AuthService.login(email, password) → Token -``` -→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types." - -### Medium confidence: same_ac_slot -``` -# Source Design Doc — AC-003 -When user submits valid credentials, the system shall create a session with 30-minute expiry - -# Other Design Doc — AC-012 -When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry -``` -→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)." - -### Not reported (no structural evidence) -``` -# Source Design Doc -Endpoint: POST /api/users/register - -# Other Design Doc -Endpoint: POST /api/accounts/signup -``` -→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence. - ## Quality Checklist - [ ] Correctly read source_design -- [ ] Surveyed all Design Docs (excluding template) +- [ ] Accounted for documents sharing the source's affected contracts and recorded material access limitations - [ ] Extracted items using extraction output format -- [ ] Applied Match Basis Rules across all sections +- [ ] Applied Detection Boundary across all sections - [ ] Every detected conflict includes confidence and match_basis - [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis - [ ] Every medium-confidence conflict includes structural evidence in reason field @@ -307,11 +208,11 @@ Endpoint: POST /api/accounts/signup ## Error Handling - **source_design not found**: Output error message and terminate -- **No target Design Docs found**: Complete normally with NO_CONFLICTS status +- **No target Design Docs found**: Complete normally with SKIPPED status - **File read failure**: Skip the file and note it in the report ## Completion Criteria -- All target files have been read +- All relevant shared obligations have been compared or an exact evidence limitation reported - Structured markdown output completed - All quality checklist items verified diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 9e3c61e3..5f39881d 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -113,8 +113,8 @@ For `prior_feedback`, the received items and the boundaries their corrections ch ## Decision -- `pass`: `issues` is empty. -- `needs_revision`: One or more issues can be repaired inside approved scope. +- `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. +- `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. - `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows-fullstack/agents/integration-test-reviewer.md b/dev-workflows-fullstack/agents/integration-test-reviewer.md index ea6c54fc..91a198ff 100644 --- a/dev-workflows-fullstack/agents/integration-test-reviewer.md +++ b/dev-workflows-fullstack/agents/integration-test-reviewer.md @@ -41,7 +41,6 @@ For the `skeleton` basis, extract the following comment patterns from the change Annotation patterns (comment syntax varies by project language): - `AC:` → Original acceptance criteria - `Behavior:` → Trigger → Process → Observable Result -- `@category:` → Test classification - `@dependency:` → Dependencies - `Verification items:` → Expected verification items (if present) diff --git a/dev-workflows-fullstack/agents/investigator.md b/dev-workflows-fullstack/agents/investigator.md index c1260fbe..38169c72 100644 --- a/dev-workflows-fullstack/agents/investigator.md +++ b/dev-workflows-fullstack/agents/investigator.md @@ -42,16 +42,16 @@ Solution derivation is out of scope for this agent. ### Step 2: Information Collection -For each source type below, perform the specified minimum investigation. Record findings even when empty ("checked [source], no relevant findings"). +Choose sources that can establish or contradict the supported causes and scope coverage. The table is a set of investigation cues, not a source quota. Record evidence used and material access limitations. -| Source | Minimum Investigation Action | +| Source | When it informs the diagnosis | |--------|------------------------------| | Code | Read files directly related to the phenomenon. Grep for error messages, function names, and class names mentioned in the problem report | | git history | Trace affected history far enough to identify the comparison baseline and changes that could alter the phenomenon. For change failures, compare the evidenced working and broken states | | Dependencies | Check package manifest for relevant packages. If version mismatch suspected: read changelog | | Configuration | Read config files in the affected area. Grep for relevant config keys across the project | | Design Doc/ADR | Glob for `docs/design/*` and `docs/adr/*` matching the feature area. Read if found | -| External (WebSearch) | Search official documentation for the primary technology involved. Search for error messages if present | +| External (WebSearch) | Consult authoritative documentation when unresolved technology behavior or version compatibility can change a cause judgment | **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values) @@ -210,7 +210,7 @@ Before output, account for every diagnosis-scope item as investigated, excluded - [ ] Determined problem type and executed diff analysis for change failures - [ ] Accounted for every diagnosis-scope item and included newly discovered areas only when they satisfy the envelope and can change causes, coverage, or counter-evidence - [ ] Mapped execution paths for each symptom (pathMap), including main path and symptom-reachable branches -- [ ] Investigated each source type from the information collection table (code, git history, dependencies, configuration, docs, external). Each source has a recorded finding or "no relevant findings" +- [ ] Evidence supports or contradicts each cause and accounts for the diagnosis scope; source selection follows the relevant uncertainty rather than a quota - [ ] Checked all nodes on mapped paths for faults (not just until the first fault was found) - [ ] Each failure point has: location, upstreamDependency, symptomExplained, causalChain (reaching a stop condition), checkStatus, evidence, comparisonAnalysis - [ ] Determined impactScope per failure point diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index 8ac6f213..04010989 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -54,8 +54,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **Reverse Engineering Information** (reverse-engineer mode only): - Target feature file paths (multiple allowed) - - Summary of modifications - - Description of impact scope + - Feature, Description, Related Files, Entry Points + - Unit Inventory when scope discovery has already supplied a baseline + - External Scope Provided: whether to reuse that boundary ## PRD Output Format @@ -117,9 +118,8 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Set specific numerical targets for quantitative metrics -- Specify measurement methods -- Enable comparison with baseline +- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check - Include all stakeholder perspectives @@ -146,7 +146,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does - [ ] Are material relationships clear in prose, a compact table, or a Mermaid diagram where needed? - [ ] **Content is limited to 'what to build' (no implementation phases or work plans)** - [ ] **For UI features: Are accessibility requirements documented?** -- [ ] **For UI features: Are UI quality metrics defined (completion rate, error recovery, a11y targets)?** +- [ ] **For UI features: Are sourced quality requirements and their observable proof represented?** ## Update Mode Operation @@ -166,9 +166,9 @@ Mode for extracting specifications from existing implementation to create PRD. U ### External Scope Handling When `External Scope Provided: true` is specified: -- Skip independent scope discovery (Step 1) +- Reuse the supplied scope and Unit Inventory instead of repeating discovery - Use provided scope data as **investigation starting point**: Feature, Description, Related Files, Entry Points -- If entry point tracing reveals files/routes outside provided scope that are directly called from entry points, **include them** and report as scope expansion in output +- Inspect an outside dependency when it establishes an in-scope behavior or contract. Expand documented feature scope only when evidence shows the original boundary omitted part of that same capability; report the reason. When external scope is NOT provided: - Execute full scope discovery independently @@ -195,52 +195,18 @@ Before documenting any claim, assess confidence level: - Prioritize Verified claims in core requirements - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous -### Reverse PRD Investigation Protocol - -**Step 1: Route & Entry Point Enumeration** (even when External Scope Provided) -- Grep for all route/endpoint definitions in the provided Related Files -- Record EACH route: HTTP method, path, handler, middleware — as written in code -- This becomes the authoritative route list for the PRD - -**Step 2: Entry Point Tracing** -For each entry point / handler identified in Step 1: -1. Read the handler/controller file -2. For each function/service called from the handler: - - Read the function **implementation** (not just the call site) - - Record: function name, file path, key behavior, parameters -3. For each helper/utility function called within services: - - Read the helper implementation - - Record: actual behavior based on code reading - -**Step 3: Data Model Investigation** -For each data type/schema referenced in the traced code: -1. Read the type definition / schema / migration file -2. Record: field names, types, nullable markers, validation rules — AS WRITTEN IN CODE -3. For enum/constant definitions: record ALL values (count them explicitly) - -**Step 4: Test File Discovery** -- Glob for test files matching the feature area (common conventions: `*test*`, `*spec*`, `*Test*`) -- For each test file found: Read it and record test case names and what behavior they verify -- For handlers/services with no test files found via Glob: record as "no tests found" - -**Step 5: Role & Permission Discovery** -- Grep for middleware, guard, role-check patterns in routes and handlers -- Record ALL roles/permissions that can access the feature (not just the primary ones) - -**Step 6: Specification Documentation** -- Apply Confidence Gating to each claim -- Accurately document specifications extracted from current implementation -- Only describe specifications clearly readable from code -- Reference the route list, data model, and test inventory from Steps 1-5 - -**Step 7: Minimal Confirmation Items** -- Only ask about truly undecidable important matters (maximum 3) -- Only parts related to business decisions, not implementation details +### Reverse PRD Investigation Boundary + +Use supplied scope and inventory as the coverage baseline; discover the feature boundary only when none is supplied. Account for every in-scope entry point at the PRD's user-behavior level. Trace implementation and tests far enough to establish observable outcomes, business rules, permissions, material error behavior and data constraints. Follow helpers, schemas or configuration when they can change one of those claims; routine internal details need no independent catalog. + +Group routes and interfaces that deliver the same requirement while preserving traceable coverage. Use existing tests as evidence, inspecting relevant assertions rather than transcribing every case. Document absent test evidence accurately. Record exact identifiers and enum values when they form a documented user/public contract; technical field inventories belong in Design Docs when needed. + +Continue across all feature behaviors and material boundaries after finding a problem. Stop investigation when the PRD claims and coverage are supported and remaining uncertainty cannot change them. Record inaccessible evidence and undecidable business intent explicitly. Ask the user only for a business decision that prevents faithful documentation; non-blocking unknowns remain documented. ### Quality Standards -- Verified content: 80%+ of core requirements -- Inferred content: 15% maximum with rationale -- Unverified content: Listed in "Undetermined Items" only -- Specification document with implementable specificity -- All routes from Step 1 are accounted for in the PRD -- All data model fields from Step 3 match the PRD's data model section + +- Core behavior claims have direct evidence; inferred intent is labeled with its basis. +- Every supplied entry point and inventory item is accounted for at the PRD abstraction level or excluded with a boundary reason. +- Permissions and independently failing observable boundaries remain represented. +- Detail supports product understanding and downstream design; internal call graphs and schema catalogs are included only when a product contract depends on them. +- Unknown business intent or metrics remain explicit instead of being fabricated to meet a percentage or template. diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 04ab10b6..6703a75d 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -219,7 +219,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Fix Execution Policy -**Continue until**: all phases pass OR a blocked condition met. #### Auto-fix Range - **Format/Style**: Use detected auto-fix command diff --git a/dev-workflows-fullstack/agents/quality-fixer.md b/dev-workflows-fullstack/agents/quality-fixer.md index 7b307aa5..6b23076e 100644 --- a/dev-workflows-fullstack/agents/quality-fixer.md +++ b/dev-workflows-fullstack/agents/quality-fixer.md @@ -193,7 +193,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Important Principles **Principles**: Follow these to maintain high-quality code: -- **Zero Error Principle**: Resolve all errors and warnings - **Correctness System Convention**: Follow strong correctness guarantees when applicable - **Test Fix Criteria**: Understand existing test intent and fix appropriately @@ -202,7 +201,6 @@ Between tool calls, briefly report: which phase is running, the command executed **Execution**: Apply fixes per coding-principles.md and testing-principles.md **Auto-fix**: Format, lint, unused imports (use project tools) **Manual fix**: Tests, contracts, logic (follow rule files) -**Continue until**: All checks pass OR blocked condition met **Required Fix Approaches** (fix at their source, not around them): - Test failures → Fix implementation or test logic to pass genuinely diff --git a/dev-workflows-fullstack/agents/scope-discoverer.md b/dev-workflows-fullstack/agents/scope-discoverer.md index 1b11cb04..1cf2222a 100644 --- a/dev-workflows-fullstack/agents/scope-discoverer.md +++ b/dev-workflows-fullstack/agents/scope-discoverer.md @@ -4,9 +4,6 @@ description: Discovers functional scope from existing codebase for reverse docum tools: Read, Grep, Glob, LS, Bash skills: - documentation-criteria - - ai-development-guide - - coding-principles - - implementation-approach - llm-friendly-context --- @@ -40,86 +37,25 @@ Document generation (PRD content, Design Doc content) is out of scope for this a Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units. -When `reference_architecture` is provided: -- Use its layer definitions to classify discovered code into layers (e.g., presentation/business/data for layered) -- Validate unit boundaries against RA expectations (units should align with layer boundaries) -- Note deviations from RA as findings in `uncertainAreas` +Use `reference_architecture` as a descriptive hint when it matches the code. Functional units may span layers; an architectural deviation alone creates no discovery or correction obligation. -### Execution Steps +### Discovery Boundary -1. **Entry Point Analysis** - - Identify routing files and map URL/endpoint to feature names - - Identify public API entry points - - If `existing_prd` is provided, read it and map PRD features to code areas +Establish coverage of the requested feature surface using repository entry points, module ownership, configuration and available tests. Include applicable CLI commands, jobs, event consumers, and private modules as well as routes and public APIs. Reuse supplied scope and existing PRDs as starting evidence. Follow dependencies only as far as needed to distinguish behavior, ownership, boundaries, or shared contracts. -2. **User Value Unit Identification** - - Group related endpoints/pages by user journey - - Identify self-contained feature sets - - Look for feature flags or configuration +Return a coherent functional unit for each independently meaningful capability. Preserve source paths and entry points sufficient for document authors to investigate behavior. Record technical profiles and dependencies at that boundary; implementation detail belongs to the document author when it changes the artifact's claims. -3. **Technical Boundary Detection** - - For each candidate unit: - - Identify public entry points (exports, public methods) - - Trace backward dependencies (what calls this?) - - Trace forward dependencies (what does this call?) - - Map module/service boundaries - - Identify interface contracts +For each unit, inventory applicable routes, test files and public exports from authoritative definitions and repository conventions. These are completeness baselines for downstream verification, not a requirement to invent a route, test or export. Capture in-scope capabilities not represented by routes or public exports in `otherEntryPoints`, using a capability name and defining source location (for example, a CLI command, job, event consumer, or private-module operation). Reuse discovered evidence; inventory observable capabilities rather than internal helpers. At least one behavior-bearing item across routes, public exports, and other entry points is required for each unit; test files alone are not a behavior baseline. -4. **Synthesis into Functional Units** - - Combine user-value groups and technical boundaries into functional units - - Each unit should represent a coherent feature with identifiable technical scope - - For each unit, identify its `valueProfile`: who uses it, what goal it serves, and what high-level capability it belongs to - - Apply Granularity Criteria (see below) +Complete coverage across relevant areas even after discovering one major feature. Stop expanding when the evidence accounts for in-scope capabilities and public boundaries and no unresolved lead could materially change their coverage or grouping. Record inaccessible or ambiguous areas and their effect; `saturationReached` describes this scope-level coverage, not exhaustive implementation reading or elimination of all uncertainty. -4.5. **Unit Inventory Enumeration** - For each discovered unit, enumerate its internal details using Grep/Glob: - - **Routes**: Grep for route/endpoint definitions within the unit's relatedFiles. Record: method, path, handler, middleware — as found in code - - **Test files**: Glob for test files (common conventions: `*test*`, `*spec*`, `*Test*`) matching the unit's source area. Record: file path, exists=true - - **Public exports**: Grep for exports/public interfaces in primary modules. Record: name, type (class/function/const), file path +### PRD Unit Grouping - Store results in `unitInventory` field per unit (see Output Format). This inventory provides completeness evidence. +Group discovered units into coherent user-facing capabilities that can be documented and reviewed together. Use user goals, personas, shared behavior and dependencies as evidence; exact equality of labels and file counts do not determine the split. Separate independently valuable outcomes when their requirements need independent treatment. Every discovered unit belongs to exactly one PRD unit's `sourceUnits`. -5. **Boundary Validation** - - Verify each unit delivers distinct user value - - Check for minimal overlap between units - - Identify shared dependencies and cross-cutting concerns +### Confidence -6. **Saturation Check** - - Expand the search only while another entry point, module, test, or interface can change discovered units, boundaries, relationships, inventories, or `uncertainAreas` - - Mark discovery as saturated when additional evidence inside `target_path`, `focus_area`, and any explicit governing boundary cannot change the output, and record what remains unexamined in `uncertainAreas` - -7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete) - - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units - - Grouping logic: units with the same `valueCategory` AND the same `userGoal` AND the same `targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units - - Every discovered unit must appear in exactly one PRD unit's `sourceUnits` - - Output as `prdUnits` alongside `discoveredUnits` (see Output Format) - -8. **Return JSON Result** - -## Granularity Criteria - -Each discovered unit should represent a Vertical Slice (see implementation-approach skill) — a coherent functional unit that spans all relevant layers — and satisfy: -1. Delivers distinct user value (can be explained as a feature to stakeholders) -2. Has identifiable technical boundaries (entry points, interfaces, related files) - -**Split signals** (unit may be too coarse): -- Multiple independent user journeys within one unit -- Multiple distinct data domains with no shared state - -**Cohesion signals** (units that may belong together): -- Units share >50% of related files -- One unit cannot function without the other -- Combined scope is still under 10 files - -Note: These signals are informational only during steps 1-6. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 7 after discovery is complete. - -## Confidence Assessment - -| Level | Triangulation Strength | Criteria | -|-------|----------------------|----------| -| high | strong | 3+ independent sources agree, clear boundaries | -| medium | moderate | 2 sources agree, boundaries mostly clear | -| low | weak | Single source only, significant ambiguity | +Base confidence on directness, authority and consistency of the evidence supporting each unit's behavior and boundary. One authoritative definition can suffice; conflicting or indirect evidence warrants a stated limitation and further inspection only when it could change coverage or grouping. ## Output Format @@ -143,8 +79,6 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "name": "Unit Name", "description": "Brief description", "confidence": "high|medium|low", - "triangulationStrength": "strong|moderate|weak", - "sourceCount": 3, "entryPoints": ["/path1", "/path2"], "relatedFiles": ["src/feature/*"], "dependencies": ["UNIT-002"], @@ -160,6 +94,7 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "infrastructureDeps": ["database", "redis-cache"] }, "unitInventory": { + "otherEntryPoints": [], "routes": [ {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"} ], @@ -200,21 +135,16 @@ Note: These signals are informational only during steps 1-6. Keep all discovered } ``` +`otherEntryPoints` items have shape `{ "name": "capability", "file": "source/path:line" }`; use an empty array when routes and public exports already cover the unit. + ## Completion Criteria - [ ] Every discovered unit has an evidence-backed user-value boundary and technical boundary -- [ ] `unitInventory` accounts for the routes, test files, and public exports found inside the requested scope -- [ ] Granularity criteria were applied and each unit carries its value profile +- [ ] `unitInventory` accounts for the routes, test files, public exports, and other entry points found inside the requested scope +- [ ] Grouping reflects coherent capabilities and each unit carries its value profile - [ ] Relationships between units and any uncertain areas or limitations are recorded -- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` (step 7, after discovery completes) - -## Self-Validation [BLOCKING — before output] +- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` -Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. +## Evidence Check -- [ ] Output is limited to scope discovery (no PRD or Design Doc content generated) -- [ ] Every discovery cites its source evidence -- [ ] Low-confidence discoveries are reported with appropriate confidence markers -- [ ] Triangulation strength reflects actual source count (weak noted when single-source) -- [ ] Saturation check was performed before concluding discovery -- [ ] `saturationReached` is true only when additional evidence inside the semantic boundary cannot change the output +Return discovery results only. Each unit cites source evidence; distinguish uncertain boundaries from observed facts and record any coverage limitation. Set `saturationReached` according to the Discovery Boundary above. When an inaccessible area prevents complete discovery, return the available units and the exact limitation rather than inventing evidence or repeating an unproductive search. diff --git a/dev-workflows-fullstack/agents/solver.md b/dev-workflows-fullstack/agents/solver.md index 432d3676..fe52b5f3 100644 --- a/dev-workflows-fullstack/agents/solver.md +++ b/dev-workflows-fullstack/agents/solver.md @@ -59,7 +59,7 @@ This agent outputs **solution derivation and recommendation presentation**. Use - Failure points without impactAnalysis (e.g., discovered during verification): treat as direct fix candidates, note missing impact assessment in residualRisks ### Step 2: Solution Divergent Thinking -Generate every materially distinct feasible solution supported by the verified cause set. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: +Test removal or narrowing, then reuse, before retaining or adding a mechanism. Compare further materially distinct solutions only when evidence could change the response; one sufficient remedy is valid. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: | Type | Definition | Application | |------|------------|-------------| @@ -74,7 +74,7 @@ Generate every materially distinct feasible solution supported by the verified c **Generated Solution Verification**: - Check if project rules have applicable guidelines -- For areas without guidelines, research current best practices via WebSearch to verify solutions align with standard approaches +- Consult authoritative external evidence only when an unresolved capability, compatibility or behavior fact could change the selected remedy - Map each solution to every confirmed failure point it resolves. Classify it as a complete remedy only when it addresses the complete supported cause set ### Step 3: Tradeoff Analysis @@ -95,7 +95,7 @@ Select from the materially distinct approaches only after the verified `closed` - Each step independently verifiable - Explicitly state dependencies between steps - Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior -- Include rollback procedures +- Include rollback or operational measures only when the proposed change affects a state or contract that requires them ## Output Format @@ -127,22 +127,24 @@ Select from the materially distinct approaches only after the verified `closed` "recommendation": { "selectedSolutionId": "S1", "rationale": "Detailed selection rationale", - "alternativeIfRejected": "Alternative solution ID if recommendation rejected", + "alternativeIfRejected": "Alternative solution ID when a sufficient alternative exists, otherwise null", "conditions": "Conditions under which this recommendation is appropriate" }, "implementationPlan": { "steps": [ - {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": "Rollback procedure if problems occur"} + {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": null} ], "criticalPoints": ["Points requiring special attention"] }, "uncertaintyHandling": { "residualRisks": ["Risks that may remain after resolution"], - "monitoringPlan": "Monitoring plan after resolution" + "monitoringPlan": null } } ``` +Populate `rollback` and `monitoringPlan` only when the selected remedy requires them; otherwise retain `null`. `alternativeIfRejected` is `null` when no decision-relevant sufficient alternative exists. + When verified cause coverage is not closed, return only: ```json @@ -158,7 +160,7 @@ When verified cause coverage is not closed, return only: The first criterion applies to both statuses. All later criteria and Self-Validation items apply only to `status: completed`. - [ ] Verified the input cause set is closed, or returned only `verification_required` with the exact next verification -- [ ] Generated every materially distinct feasible solution and counted only different mechanisms or scope decisions when the precondition passed +- [ ] Compared decision-relevant remedies, starting with subtraction and reuse, and selected a sufficient response to the complete verified cause set - [ ] Analyzed tradeoffs for each solution - [ ] Selected recommendation and explained rationale - [ ] Created concrete implementation steps diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index e4ad5039..428b906d 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -71,7 +71,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Component Reuse Decision Five indicators: (a) same domain/responsibility (same UI pattern, same business domain), (b) same input/output pattern (Props type/structure), (c) same rendering content (JSX structure, event handlers, state management), (d) same placement (same component directory or related feature), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -151,9 +151,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: -□ **Repository-wide verification**: confirm the pattern, hook, or library is representative across the repository (not just the nearest 2-3 components) -□ **Coexistence resolution**: when multiple libraries or patterns coexist for the same concern (routing, server-state, forms, styling, etc.), follow the dominant choice in the **changed feature area** — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no dominant choice is clear, select from the repository choices already established for the concern and record the evidence for that selection -□ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. @@ -178,7 +176,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -187,11 +185,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -210,7 +208,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -228,12 +230,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar component or hook and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index 24abb82b..161d9263 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -66,7 +66,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Function Reuse Decision Five indicators: (a) same domain/responsibility (business domain, processing entity), (b) same input/output pattern (argument/return contract/structure), (c) same processing content (CRUD/validation/transformation/calculation logic), (d) same placement (same directory or related module), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -146,9 +146,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: -□ **Repository-wide verification**: confirm the pattern or dependency version is representative across the repository (not just the nearest 2-3 files) -□ **Dependency version verification** (external deps): verify repo-wide usage distribution; follow the version representative of the changed area and record that evidence when multiple versions coexist -□ **Coexistence resolution**: when multiple versions or patterns coexist, identify the majority for the changed area before choosing. When no established choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow @@ -174,7 +172,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -183,11 +181,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -206,7 +204,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -224,12 +226,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar implementation and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index 270056e4..b700db96 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -22,7 +22,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -113,7 +115,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 63ace229..4fc6ccba 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -21,7 +21,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -119,7 +121,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/dev-workflows-fullstack/agents/verifier.md b/dev-workflows-fullstack/agents/verifier.md index c483651d..ccccf51b 100644 --- a/dev-workflows-fullstack/agents/verifier.md +++ b/dev-workflows-fullstack/agents/verifier.md @@ -43,19 +43,13 @@ Solution derivation is out of scope for this agent. **impactAnalysis Validity Check**: - Verify the logical validity of each failure point's impactAnalysis using only the supplied investigation evidence; perform additional searches in Step 2 -### Step 2: Triangulation Supplementation -Identify source types NOT covered in the investigation's `investigationSources`, then investigate at least one: +### Step 2: Independent Evidence Check -1. Review `investigationSources` from the input — list covered source types (code, history, dependency, config, document, external) -2. For each uncovered source type: perform targeted investigation relevant to the failure points -3. If all source types were covered: investigate a **different code area** or **different configuration** not mentioned in the original investigation +Independently check the decisive claims, counter-evidence and scope closure against their authoritative sources. Expand to another source or area only when it can change a failure-point judgment or close a material coverage gap. An already decisive source needs no unrelated corroboration. Record the evidence and its effect. -Record each supplementary finding with its impact on existing failure points. +### Step 3: External Evidence (Conditional) -### Step 3: External Information Reinforcement (WebSearch) -- Official information about failure points found in investigation -- Similar problem reports and resolution cases -- Technical documentation not referenced in investigation +Consult authoritative external sources when an unresolved technology behavior, dependency capability or version fact can change the diagnosis and repository evidence cannot decide it. ### Step 4: Investigation Coverage Check Check the upstream investigation's pathMap for completeness: @@ -123,12 +117,8 @@ Set `coverageDisposition` independently: "pathMapCoverage": "Assessment of path coverage completeness", "identifiedGaps": ["Missing paths or unchecked nodes"] }, - "triangulationSupplements": [ - {"source": "Additional information source investigated", "findings": "Content discovered", "impactOnFailurePoints": "Impact on existing failure points"} - ], - "externalResearch": [ - {"query": "Search query used", "source": "Information source", "findings": "Related information discovered", "impactOnFailurePoints": "Impact on failure points"} - ], + "triangulationSupplements": [], + "externalResearch": [], "coverageCheck": { "scopeEnvelopeAccounting": [ {"scopeItem": "Scope-envelope item", "status": "closed|material_gap|evidence_unavailable", "evidence": "Coverage evidence", "nextInvestigationTarget": "Exact target or null"} @@ -166,8 +156,8 @@ Set `coverageDisposition` independently: ## Completion Criteria -- [ ] Performed Triangulation supplementation and collected additional information -- [ ] Collected external information via WebSearch +- [ ] Independently verified decisive evidence and closed material coverage gaps +- [ ] Used external evidence when unresolved technology facts could change the diagnosis - [ ] Checked pathMap coverage (missing paths, unchecked nodes) - [ ] Performed Devil's Advocate evaluation on each failure point - [ ] Weakened finalStatus for failure points with official documentation-based counter-evidence diff --git a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md index fd97e36d..b3c9e991 100644 --- a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md @@ -68,7 +68,7 @@ Make all errors visible and traceable with full context. Prioritize primary code - The same failure is caught at multiple layers without a single recovery owner - Nested handlers obscure which state is committed, rolled back, or exposed - A handler converts a failure to success/default output without an observable degraded-state contract -- Error handlers that return default values without logging +- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal. @@ -143,7 +143,7 @@ Keep concrete implementations separate while their apparent similarity is accide - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis +- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness diff --git a/dev-workflows-fullstack/skills/coding-principles/SKILL.md b/dev-workflows-fullstack/skills/coding-principles/SKILL.md index af2be9c8..bd3ede0b 100644 --- a/dev-workflows-fullstack/skills/coding-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/coding-principles/SKILL.md @@ -70,15 +70,9 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -### Verifying References Before Adoption -When adopting patterns, APIs, or dependencies from existing code: -- **IF** a reference sample covers only nearby files → **THEN** confirm the pattern is representative by checking relevant repository usage before adopting -- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient -- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it -- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update) - -### Principle -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model. +Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md index d1892ee8..8d814d76 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md @@ -94,6 +94,8 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r ## Success Criteria +State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. + ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] 2. [Metric name]: [numeric target] measured by [method] within [timeframe] @@ -134,7 +136,7 @@ Include only evidenced product or delivery risks that can change scope, success - [ ] [Question 1]: [Description of options or impacts] - [ ] [Question 2]: [Description of options or impacts] -*Discuss with user until this section is empty, then delete after confirmation* +Resolve only questions that block the current document or next decision. Retain non-blocking unknowns with their effect; in as-is documentation, unknown business intent is not a reason to invent requirements. ## Appendix diff --git a/dev-workflows-fullstack/skills/external-resource-context/SKILL.md b/dev-workflows-fullstack/skills/external-resource-context/SKILL.md index 344caaea..1c4da6e7 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/SKILL.md +++ b/dev-workflows-fullstack/skills/external-resource-context/SKILL.md @@ -36,17 +36,17 @@ When the file is absent or the resource is unreachable, continue from governing ## Capturing and Updating Records -Capturing a record requires an interactive hearing. The workflow using this skill owns the interaction mechanism and routing. Follow [references/hearing.md](references/hearing.md) for the hearing conditions, domain routing, two-phase hearing, storage protocol, and quality checklist. +Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow [references/hearing.md](references/hearing.md) for evidence, questions and storage. ## Output Format -The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. +Use [references/template.md](references/template.md) for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence. For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). ## References -- [references/hearing.md](references/hearing.md) — Hearing conditions, domain routing, storage protocol, quality checklist +- [references/hearing.md](references/hearing.md) — Decision-specific capture and storage - [references/frontend.md](references/frontend.md) — Frontend domain axes - [references/backend.md](references/backend.md) — Backend domain axes - [references/api.md](references/api.md) — API contract domain axes diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/api.md b/dev-workflows-fullstack/skills/external-resource-context/references/api.md index b9a3510e..42d2a3db 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/api.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/api.md @@ -1,60 +1,10 @@ -# API Contract Domain Axes +# Api Resource Cues -Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: API Schema Source +- **Schema**: OpenAPI, Protobuf, GraphQL or code-first definition for the affected API. +- **Mock environment**: Existing entry point and whether it preserves the claimed contract. +- **Authentication**: Mechanism and credential-source reference needed for authorized verification. +- **Schema change process**: Versioning or compatibility rule governing the changed contract. -The canonical source of API contracts (request/response shapes, endpoints, RPC methods). - -**Question choices**: -- OpenAPI / Swagger specification (file in repository or hosted URL) -- Protobuf definitions (file in repository) -- GraphQL schema (SDL file or introspection endpoint) -- TypeScript or other code-first contract definitions in the repository -- No formal contract (ad-hoc JSON) -- Not applicable - -**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. - -## Axis 2: Mock Environment - -How clients exercise the API without depending on the live server. - -**Question choices**: -- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) -- Hand-written mock server in the repository -- Hosted mock service (URL) -- Live development server (no separate mock) -- Not applicable - -**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. - -## Axis 3: Authentication Method - -How the API authenticates and authorizes requests. - -**Question choices**: -- Bearer token (e.g., JWT) issued by an auth service -- API key in a header or query parameter -- Session cookie set by a separate login flow -- Mutual TLS -- No authentication -- Not applicable - -**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. - -## Axis 4: Schema Change Process (When Relevant) - -How breaking and non-breaking schema changes are reviewed and rolled out. - -**Question choices**: -- Documented contract review process (link to the document) -- Versioned endpoints (e.g., `/v1/`, `/v2/`) -- Backward-compatible changes only, no formal versioning -- Not applicable - -**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/backend.md b/dev-workflows-fullstack/skills/external-resource-context/references/backend.md index ffc27403..2d9c0535 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/backend.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/backend.md @@ -1,60 +1,10 @@ -# Backend Domain Axes +# Backend Resource Cues -Hearing axes for tasks that involve server-side, data, or storage work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Database Schema Source +- **Database schema**: Authoritative migration, schema file or registry for the affected contract. +- **Migration history**: Relevant tool and history when state conversion affects the decision. +- **Secret store**: Location and retrieval mechanism only; keep secret values out of records. +- **Background jobs**: Queue or scheduler and inspection method when delivery behavior matters. -The canonical source of the database schema (tables, columns, indexes, constraints). - -**Question choices**: -- Migration files in the repository (e.g., a `migrations/` directory) -- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) -- Database MCP that introspects a live database -- External schema registry (URL or hosted catalog) -- No persistent database -- Not applicable - -**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. - -## Axis 2: Migration History - -How schema changes are tracked over time. - -**Question choices**: -- Versioned migration files in the repository -- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) -- Manual change log document -- No migration tracking -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. - -## Axis 3: Secret Store - -Where credentials, API keys, and other secrets are stored and accessed. - -**Question choices**: -- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) -- Environment variables loaded from a `.env` file (development only) -- Encrypted file in the repository -- No secrets required -- Not applicable - -**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. - -## Axis 4: Background Job Infrastructure (When Relevant) - -How asynchronous work is dispatched and observed. - -**Question choices**: -- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) -- Cron / scheduled tasks managed by deployment platform -- In-process worker thread -- No background work -- Not applicable - -**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/frontend.md b/dev-workflows-fullstack/skills/external-resource-context/references/frontend.md index b90b4e29..76ae7d6e 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/frontend.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/frontend.md @@ -1,60 +1,10 @@ -# Frontend Domain Axes +# Frontend Resource Cues -Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Design Origin +- **Design origin**: Canonical visual source or specification and the applicable node/version. +- **Design system**: Component/token documentation or package that determines this UI contract. +- **Guidelines**: A sourced usage or accessibility requirement that constrains this change. +- **Visual verification**: Existing rendering entry point, harness or access method needed to observe the UI. -The canonical source of the visual specification. - -**Question choices**: -- Design tool (e.g., a hosted design platform) -- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) -- Public documentation URL -- Existing implementation only (no separate design source) -- Not applicable - -**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. - -## Axis 2: Design System - -Reusable component library and design tokens. - -**Question choices**: -- Component library with MCP server access -- Component library with documentation URL -- Storybook or equivalent component catalog -- Internal package without external documentation -- No design system (ad-hoc components) -- Not applicable - -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. - -## Axis 3: Guidelines - -Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. - -**Question choices**: -- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) -- External documentation site -- Inline guidance in the design system catalog -- No documented guidelines -- Not applicable - -**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. - -## Axis 4: Visual Verification Environment - -How rendered output is confirmed during implementation. - -**Question choices**: -- End-to-end test runner with screenshot capability -- Storybook or equivalent isolated component preview -- Browser automation tool (dedicated CLI or MCP server) -- Manual browser inspection only -- Not applicable - -**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/hearing.md b/dev-workflows-fullstack/skills/external-resource-context/references/hearing.md index e81156f3..971c0bc2 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/hearing.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/hearing.md @@ -1,52 +1,18 @@ -# External Resource Hearing and Storage +# External Resource Capture -Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism. +Capture a resource only when repository and supplied evidence cannot decide a current design, implementation or verification question without it. Absence of a project record does not trigger a domain-wide questionnaire. -## When to Hear +## Resolve Access -| Condition | Action | -|-----------|--------| -| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | -| File exists and covers the current decision | Use it without an update question | -| The governing request identifies changed environment facts | Run diff-only hearing for the named axes | -| A relevant axis is absent | Hear only the missing axis | -| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation | +1. Name the decision and required external fact. Read the existing project entry and feature identifier when available. +2. Reuse access details from the user, governing artifacts or repository configuration. Fetch the selected content within current authority. A new record can be written from this evidence without a hearing. +3. Ask only for a missing location, access method or user-owned interpretation that prevents the decision. The calling workflow owns interaction; an autonomous consumer returns the exact missing evidence to that caller and continues independent work. +4. Correct stale details when authoritative current evidence establishes the replacement. When it does not, preserve the last known record, report the failed access and ask only for the unresolved decision-relevant fact. Record locations and access mechanisms, never secret values. -## Domain Routing +## Optional Domain Cues -Load the domain reference matching the current task: +Load only the reference needed to locate the selected fact: [frontend.md](frontend.md), [backend.md](backend.md), [api.md](api.md), or [infra.md](infra.md). Their lists are cues, not required questions or completion axes. -| Task type | References to load | -|-----------|--------------------| -| Frontend (UI work) | [frontend.md](frontend.md) | -| Backend (server / data work) | [backend.md](backend.md) | -| API contract work | [api.md](api.md) | -| Infrastructure / deployment | [infra.md](infra.md) | -| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure | +## Store -Each domain reference defines the axes and the question template. - -## Two-Phase Hearing - -1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). - -2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration. - -For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis. - -## Storage Protocol - -After hearing completes: - -1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure. -2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. -3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). -4. Report the file paths back to the calling workflow. - -## Quality Checklist - -- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" -- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes -- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command) -- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier -- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision +Use [template.md](template.md) for `docs/project-context/external-resources.md`. Keep environment facts at project level and feature-specific identifiers in the consuming document's `External Resources Used` table. Preserve unrelated entries and stable labels. Create no empty record or N/A catalog when no external source is required. Return changed paths and any exact remaining evidence limitation to the caller. diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/infra.md b/dev-workflows-fullstack/skills/external-resource-context/references/infra.md index 932a416d..0529df4d 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/infra.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/infra.md @@ -1,60 +1,10 @@ -# Infrastructure Domain Axes +# Infra Resource Cues -Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: IaC Source +- **IaC source**: Relevant checked-in or external infrastructure definition. +- **Environment configuration**: Configuration source for the specific environment and question. +- **Secrets**: Secret-store reference and access mechanism, never values. +- **Deployment trigger**: Existing execution/approval boundary only when it affects current implementation or verification. -The canonical source of infrastructure definitions. - -**Question choices**: -- Terraform configuration in the repository -- Pulumi or CDK code in the repository -- Kubernetes manifests / Helm charts in the repository -- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) -- Manual console configuration (no IaC) -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. - -## Axis 2: Environment Configuration - -How per-environment settings (development, staging, production) differ. - -**Question choices**: -- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) -- Environment variables managed by the deployment platform -- Workspace or stack abstraction in the IaC tool itself -- Single shared configuration (no per-environment differences) -- Not applicable - -**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. - -## Axis 3: Secrets in Infrastructure - -How infrastructure code references secrets without exposing them. - -**Question choices**: -- Secrets sourced from a secret manager via IaC data lookup -- Secrets injected at apply time via environment variables -- Encrypted secret files committed alongside IaC -- No secrets in infrastructure -- Not applicable - -**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. - -## Axis 4: Deployment Trigger - -How infrastructure and application changes reach environments. - -**Question choices**: -- CI pipeline triggered on merge to a specific branch -- Manual approval step in CI -- Local apply by an operator -- Deployment platform's auto-deploy on push -- Not applicable - -**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows-fullstack/skills/external-resource-context/references/template.md b/dev-workflows-fullstack/skills/external-resource-context/references/template.md index 169f3b29..8321a7ac 100644 --- a/dev-workflows-fullstack/skills/external-resource-context/references/template.md +++ b/dev-workflows-fullstack/skills/external-resource-context/references/template.md @@ -1,115 +1,31 @@ # Storage Templates -Two templates: the project-tier file and the feature-tier section. +## Project Record -## Project-Tier Template - -Path: `docs/project-context/external-resources.md` +Path: `docs/project-context/external-resources.md`. Preserve existing resource labels referenced by feature documents. Include only resources actually needed; adapt grouping to the existing file. ```markdown # External Resources -Last updated: YYYY-MM-DD - -This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. - -## Frontend - -### Design Origin -- Status: -- Source type: -- Location: -- Access method: - -### Design System -- Status: -- Source type: -- Location: -- Access method: - -### Guidelines -- Status: -- Source type: -- Location: -- Access method: - -### Visual Verification Environment -- Status: -- Tool type: -- Entry: - -## Backend - -### Database Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Migration History -- Status: -- Tool: -- Location: -- Apply trigger: - -### Secret Store -- Status: -- Service: -- Access method: - -### Background Job Infrastructure -- Status: -- Service: -- Access method: - -## API - -### API Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Mock Environment -- Status: -- Source type: -- Entry: - -### Authentication Method -- Status: -- Mechanism: -- Credential source: - -### Schema Change Process -- Status: -- Process: - -## Infrastructure - -### IaC Source -- Status: -- Tool: -- Location: -- Apply trigger: - -### Environment Configuration -- Status: -- Mechanism: -- Environments: +## [Stable resource label] +- Purpose: [decision or contract served] +- Location: [URL, path, package or service] +- Access method: [read operation, tool or command within existing authority] +- Evidence: [source and relevant version/date] +``` -### Secrets in Infrastructure -- Status: -- Mechanism: +Keep credentials and secret values outside this record. Record an access limitation when it affects a consumer; a failed fetch does not establish that the resource is absent. -### Deployment Trigger -- Status: -- Mechanism: +## Feature Reference -## Additional Resources +Use the consuming document's natural heading level for `External Resources Used`. -Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. +```markdown +## External Resources Used -- : — — +| Project resource label | Feature-specific identifier | Use | +|---|---|---| +| [existing label] | [node, endpoint, module or version selector] | [decision or proof] | ``` -Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). +Project entries own shared locations and access methods; feature rows own only the subset and identifiers used here. diff --git a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md index 53987b3b..aa037f1f 100644 --- a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md @@ -1,121 +1,17 @@ --- name: integration-e2e-testing -description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when designing integration tests, E2E tests, or reviewing test quality. +description: Defines integration/E2E skeleton annotations, lane and file contracts, and route-parity review criteria. Use when generating or consuming test skeletons or reviewing shared mutation routes. --- -# Integration and E2E Testing Principles +# Integration and E2E Skeleton Contracts -## References +## Test Lanes -**E2E test design**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection. - -## Test Type Definition and Standard Budgets - -| Test Type | Purpose | Scope | External Deps | Standard Budget per Input Design Doc | Implementation Timing | -|-----------|---------|-------|---------------|-------------------|----------------------| -| Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | -| fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | - -**Lane selection (E2E only)**: -- Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup -- Add **service-integration-e2e** only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely - -One input Design Doc is one budget scope: apply each lane budget once across all ACs and candidates in that document. The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa. Treat the numbers above as enforced standard budgets. Exceed a budget only when an accepted requirement or a distinct failure mode cannot be proved by a selected test; annotate that exception and why consolidation cannot cover it. - -## Behavior-First Principle - -### Include (High ROI) -- Business state transitions observable across components -- Data integrity and persistence behavior -- User-visible functionality completeness -- Error handling behavior (what user sees/experiences) - -### Redirect to Other Test Types -- Calculation and data transformation rules → Verify via unit tests of the logic that owns them -- External service connections → Verify via contract/interface tests -- Performance metrics → Verify via dedicated load testing -- Implementation details → Verify observable behavior instead -- UI layout specifics → Verify information availability instead - -**Principle**: Test = User-observable behavior verifiable in isolated CI environment - -## ROI Calculation - -ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently. - -For every candidate, record the governing evidence for each ROI input before assigning a value. Use an approved PRD, confirmed requirement context, accepted contract or legal obligation, user-confirmed test value context, Design Doc boundary, and existing-test evidence as applicable. A missing value is `unknown`, not `0`, and an inference is not observed evidence. - -When ROI can change candidate ranking, a lane threshold, or budget selection, return the exact missing product input and its decision effect when `test_value_context` has not yet supplied it. After that single input round, apply the supplied facts and retain every remaining value as decision-relevant `unknown` with its numeric score unset. Resolve Defect Detection from repository evidence at the proof boundary and in existing tests. When selection is invariant because the candidate is removed before ROI, is the sole eligible candidate for a reserved journey slot, or all surviving candidates fit an unthresholded budget, record the unknown as `not_decision_relevant` and keep its numeric score unset. - -### Unknown-Value Ordering - -For candidates with a decision-relevant `unknown` after the value-input round, use accepted legal or contractual obligation, explicit connection to the confirmed user or business outcome, distinct Defect Detection evidence, lower lane ownership cost, then source AC order. Select the smallest set that proves the accepted obligations and confirmed outcome boundaries, within the normal lane budgets. Numeric lane thresholds apply to fully scored candidates; this evidence ordering supplies the selection decision for affected candidates. Record the unknown input, evidence checked, and selection effect. - -For resolved numeric inputs, use exactly `0`, `5`, or `10`. Legal Requirement remains boolean; a governing-source check that finds no accepted legal, regulatory, contractual, or audit obligation supports `false` and records that checked source. - -| Input | Scale | -|---|---| -| Business Value | 0 = no user/business outcome; 5 = meaningful but non-critical outcome; 10 = core, revenue, safety, or data-integrity outcome | -| User Frequency | 0 = unreachable/obsolete; 5 = regular subset of users or runs; 10 = dominant journey or execution path | -| Legal Requirement | `true` only when an accepted legal, regulatory, contractual, or audit requirement applies; otherwise `false` | -| Defect Detection | 0 = duplicates existing proof; 5 = covers a distinct branch/state; 10 = uniquely detects a critical boundary or cross-service failure | - -``` -ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection - (range: 0–120) -``` - -Higher ROI Score = higher priority within its test type. For equal scores, order by Legal Requirement (`true` first), then higher Defect Detection, Business Value, User Frequency, and finally source AC order. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores. - -### ROI Thresholds by Lane - -The two E2E lanes have different ownership costs and use independent standard thresholds. - -| Lane | ROI threshold | Rationale | -|------|---------------|-----------| -| fixture-e2e | ROI ≥ 20 (beyond reserved slot) | Cost is comparable to integration tests once the harness exists; the floor avoids filling MAX 3 with low-signal tests when fewer would suffice | -| service-integration-e2e | ROI > 50 (beyond reserved slot) | Live-service setup, state cleanup, and failure diagnosis add material ownership cost; reserve for journeys whose value cannot be proven any other way | - -Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Emit a below-floor candidate beyond the reserved slot only when an accepted requirement or a distinct uncovered failure mode justifies the exception. Leave budget intentionally unfilled rather than padding with low-value tests; record any threshold or budget exception in the skeleton that carries the exception. - -### ROI Calculation Examples - -| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome | -|----------|----|------|-------|--------|-----------|-----------|-------------------| -| Core checkout UI flow | 10 | 10 | true | 10 | 120 | fixture-e2e | Selected (reserved slot: user-facing multi-step journey, browser-level verification with fixtures) | -| Core checkout against live payment service | 10 | 10 | true | 10 | 120 | service-integration-e2e | Selected (real-service correctness above ROI threshold) | -| Dismiss button updates UI state | 5 | 10 | false | 5 | 55 | fixture-e2e | Selected (rank 2 of 3 fixture-e2e budget) | -| Payment error message display | 5 | 5 | false | 5 | 30 | fixture-e2e | Selected (rank 3 of 3 fixture-e2e budget) | -| Optional filter toggle | 5 | 5 | false | 0 | 25 | fixture-e2e | Removed during deduplication (duplicates existing proof) | -| Payment retry against real provider | 5 | 5 | false | 5 | 30 | service-integration-e2e | Below ROI threshold (30 < 50), not selected | -| DB persistence check | 10 | 5 | false | 10 | 60 | Integration | Selected (rank 1 of 3) | -| Pure data transformation | 5 | 5 | false | 5 | 30 | Unit | Not selected (push down to unit test) | - -## Multi-Step User Journey Definition - -A candidate qualifies as a **multi-step user journey** when ALL of the following are true: - -1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type: - - Web: distinct routes/pages - - Mobile native: distinct screens/views - - CLI: distinct command invocations or interactive prompts - - API: distinct API calls forming a transaction (e.g., create → confirm → finalize) -2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays -3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow) - -### User-Facing vs Service-Internal Journeys - -Multi-step journeys are classified for reserved-slot eligibility: - -| Classification | Condition | Reserved Slot Eligibility | Example | -|---|---|---|---| -| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible — defaults to **fixture-e2e** reserved slot. Add a service-integration-e2e reserved slot only when the journey's correctness depends on real cross-service behavior | Web checkout flow, CLI setup wizard, mobile onboarding | -| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot — use integration tests. Service-integration-e2e through normal ROI > 50 path is still valid when full-system verification is warranted | Async job pipeline, service-to-service saga, scheduled batch processing | - -This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above. - -Use this definition when evaluating E2E test candidates and E2E gap detection. +| Lane | Observable boundary | Dependencies | +|------|---------------------|--------------| +| `integration` | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary | +| `fixture-e2e` | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary | +| `service-integration-e2e` | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary | ## Test Skeleton Specification @@ -126,18 +22,11 @@ Each test MUST include the following annotations: ``` AC: [Original acceptance criteria text] Behavior: [Trigger] → [Process] → [Observable Result] -@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e @lane: integration | fixture-e2e | service-integration-e2e @dependency: none | [component names] | full-system -@complexity: low | medium | high -ROI: [score] +Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient] ``` -**`@lane` selection rule**: -- `integration` — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language) -- `fixture-e2e` — Browser-level UI verification with mocked backend / fixture-driven state -- `service-integration-e2e` — Browser-level or end-to-end verification against running local services or stubs - Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). ### Verification Items (Optional) @@ -149,33 +38,14 @@ Verification items: - [Item 2] ``` -## EARS Format Mapping - -| EARS Keyword | Test Type | Generation Approach | -|--------------|-----------|---------------------| -| **When** | Event-driven | Trigger event → verify outcome | -| **While** | State condition | Setup state → verify behavior | -| **If-then** | Branch coverage | Both condition paths verified | -| (none) | Basic functionality | Direct invocation → verify result | - ## Test File Naming Convention - Integration tests: `*.int.test.*` or `*.integration.test.*` - fixture-e2e tests: `*.fixture.e2e.test.*` (or organize under `tests/e2e/fixture/`) - service-integration-e2e tests: `*.service.e2e.test.*` (or organize under `tests/e2e/service/`) -The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing and budget accounting. - -## Review Criteria - -### Skeleton and Implementation Consistency - -| Check | Failure Condition | -|-------|-------------------| -| Behavior Verification | No assertion for "observable result" in the implemented test | -| Verification Item Coverage | Listed items not all covered by assertions | -| Mock Boundary | Internal components mocked in integration test | +The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing. -### Route Parity for Shared Mutations +## Route Parity for Shared Mutations -When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure. diff --git a/dev-workflows-fullstack/skills/integration-e2e-testing/references/e2e-design.md b/dev-workflows-fullstack/skills/integration-e2e-testing/references/e2e-design.md deleted file mode 100644 index 7c1e95a0..00000000 --- a/dev-workflows-fullstack/skills/integration-e2e-testing/references/e2e-design.md +++ /dev/null @@ -1,72 +0,0 @@ -# E2E Test Design (Browser Harness) - -This reference uses Playwright as the default browser harness. Adapt patterns to the project's chosen framework when different (Cypress, Selenium, etc.); the lane definitions, ROI rules, and budgets remain the same. - -## Two E2E Lanes - -E2E tests in this workflow split into two lanes (see parent skill Test Type Definition): - -| Lane | When | ROI gate | Cost | -|------|------|----------|------| -| **fixture-e2e** | UI journey verification with deterministic fixtures (mocked backend / fixture data) | ROI ≥ 20 (beyond reserved slot); selected by ranking within MAX 3 budget | Comparable to integration; runs in CI without infrastructure setup | -| **service-integration-e2e** | Journey correctness depends on real cross-service behavior (data persistence, transactional consistency, external contracts) | ROI > 50 (beyond reserved slot) | Higher setup, state-cleanup, and diagnosis cost; reserved for what cannot be faked safely | - -The **reserved slot** referenced in the ROI gates is a per-lane slot for a qualifying multi-step user journey that is emitted regardless of its ROI score; it is defined in the parent skill's *Multi-Step User Journey Definition* section. - -## When to Create E2E Tests - -E2E candidates target **critical user journeys** that span multiple pages or require real browser interaction. Pick the lane based on whether real services are required for the verification. - -### Candidate Sources - -| Source | What to Extract | -|--------|----------------| -| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens | -| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) | -| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification | -| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) | - -### Selection Criteria - -**Include** (high E2E ROI): -- Multi-page user journeys (login → dashboard → action → confirmation) -- Flows requiring real browser APIs (navigation, cookies, localStorage) -- Accessibility verification requiring actual DOM rendering -- Responsive behavior across viewports - -**Use integration tests instead when**: -- Testing single-component state changes → in-process component renderer (e.g., RTL for React/TS) -- Testing API response handling → in-process API mock + component renderer (e.g., MSW + RTL for React/TS) -- Testing pure data transformations → unit tests - -## UI Spec to E2E Test Mapping - -When a UI Spec exists, use it as the primary source for E2E test design: - -1. **Extract screen transitions** → Each multi-step transition = 1 E2E candidate -2. **Check state x display matrix** → Error states requiring navigation = E2E candidate -3. **Review interaction definitions** → Browser-dependent interactions = E2E candidate -4. **Cross-reference with Design Doc ACs** → Ensure E2E candidates map to acceptance criteria - -### Mapping Template - -``` -Screen Transition: [Screen A] → [Screen B] → [Screen C] -AC Reference: AC-{id} -User Journey: [Description of what the user accomplishes] -Lane: fixture-e2e | service-integration-e2e -Preconditions: [Auth state, data state — note whether these are fixture-driven or live] -Verification Points: - - [What to assert at each step] -E2E ROI Score: [calculated score] -``` - -**Lane decision**: choose `fixture-e2e` by default. Promote to `service-integration-e2e` when the verification requires observing real cross-service behavior (e.g., the test asserts that data persists across a real DB write, or that an external service receives the correct payload). - -## Budget Enforcement - -Standard budgets per input Design Doc (same as parent skill): -- **fixture-e2e**: MAX 3 tests, ROI ≥ 20 beyond the reserved slot (selected by ranking) -- **service-integration-e2e**: MAX 1-2 tests, ROI > 50 beyond the reserved slot -- Prefer fewer, comprehensive journey tests over many granular tests in both lanes -- Exceed a standard budget only for an accepted requirement or distinct uncovered failure mode, and record why the selected tests cannot be consolidated diff --git a/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md b/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md index 73cc23e6..6ff8fcf1 100644 --- a/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md +++ b/dev-workflows-fullstack/skills/llm-friendly-context/SKILL.md @@ -16,7 +16,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Example: "Preserve existing public API behavior across the documented compatibility cases." 2. **Make vague instructions concrete** - - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions. - Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. 3. **Specify output shape** @@ -30,7 +30,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Follow references while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task. - Each step needs a checkpoint: what evidence proves it is complete. 6. **Permit uncertainty explicitly** @@ -40,7 +40,7 @@ The goal is stable downstream execution: the next consumer should know what to r 7. **Keep constraints proportionate** - Add only constraints that reduce ambiguity or preserve a real requirement. - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. - - Apply `minimal`, `a few lines`, and explicit line estimates to the completed diff as one total budget. + - Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count. ## Rewrite Patterns @@ -49,7 +49,7 @@ Use these rewrites before treating a prompt, handoff, or artifact as complete. | Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | -| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule | +| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | @@ -68,7 +68,7 @@ Before sending a prompt or artifact to another consumer, verify: - [ ] Accepted decisions and constraints use one canonical wording. - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. -- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains. - [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative. - [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner. diff --git a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md index 1a46bb6a..12b0542a 100644 --- a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md @@ -43,14 +43,7 @@ Document paths: $ARGUMENTS ### Step 1: Discover and Validate Documents -Confirm `$ARGUMENTS` names at least one existing document path; report and end when it is empty or every path is unresolvable. Then discover the remaining Design Docs, UI Specs, and PRDs under `docs/design/`, `docs/ui-spec/`, and `docs/prd/`. - -Classify discovered documents by filename: -- Filename contains `backend` → **Design Doc (backend)** -- Filename contains `frontend` → **Design Doc (frontend)** -- Located in `docs/ui-spec/` → **UI Spec** (optional) -- Located in `docs/prd/` → **approved PRD / confirmed requirement context** (optional; prefer the path named by the Design Doc) -- None of the above → treat as single-layer Design Doc +Resolve the documents named by `$ARGUMENTS`; when a supplied path is stale, use repository evidence to locate its intended artifact. Use the requested feature and layers as the discovery boundary. Resolve applicable Design Docs and UI Specs/PRDs within that boundary, including same-feature frontend/backend counterparts when fullstack work is requested, even when the named document does not link them. Use feature identity, governing requirements, and implementation ownership to establish relevance; stop once the requested layers and proof boundaries are covered. An explicitly single-layer request remains single-layer. Classify documents from their content and references; filenames are hints. Report an exact missing prerequisite when no applicable Design Doc can be resolved. ### Step 2: Skeleton Generation @@ -61,7 +54,7 @@ Invoke acceptance-test-generator using Agent tool: - `ui_spec`: Existing UI Spec path when present - `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record -Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation before Step 3. +Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. **Expected output**: `generatedFiles` containing integration and e2e paths diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index e93ed154..e51b2ec8 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -85,7 +85,7 @@ When `adrDecisionPoints` is non-empty: 1. Invoke `dev-workflows-fullstack:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. 2. Invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. ## Step 5: Create the Design Doc diff --git a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md index 25c5da5e..687bd7f1 100644 --- a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md @@ -85,7 +85,7 @@ Review investigation output: - [ ] Each failure point has: `location`, `upstreamDependency`, `symptomExplained`, `causalChain` (reaching a stop condition), `checkStatus`, `evidence` with a `source` citing a specific file or location - [ ] Each failure point has `comparisonAnalysis` (normalImplementation found or explicitly null) - [ ] `causeCategory` for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor -- [ ] `investigationSources` covers at least 3 distinct source types (code, history, dependency, config, document, external) +- [ ] `investigationSources` supplies decisive evidence for the reported causes and scope coverage; material evidence gaps are explicit - [ ] All nodes on mapped paths have been checked (no path was abandoned after finding the first fault) - [ ] `scopeAccounting` accounts for every scope-envelope item as investigated, excluded with governing evidence, or unavailable with its potential effect diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index 3ede72a2..ec9437c8 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -16,7 +16,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Execution Protocol**: 1. **Delegate to subagents** (one-shot calls): quality-fixer-frontend. -2. **Run in the parent session** (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. +2. **Run in the parent session** (multi-step loops and user dialogs): conditional external-evidence resolution, with AskUserQuestion for missing decision-relevant inputs, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. 3. **Stop at every `[Stop: ...]` marker** before proceeding. ## Execution Gate @@ -44,7 +44,7 @@ Adjustment request → conditional external resource evidence ## Scope Boundaries **Included in this skill**: -- External resource hearing per the external-resource-context skill +- Conditional external-evidence resolution per the external-resource-context skill - Existing-pattern and write-set inspection in the parent session - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) @@ -59,10 +59,10 @@ Adjustment request: $ARGUMENTS ## Execution Flow -### Step 1: External Resource Hearing -Execute Skill: external-resource-context before running the hearing protocol. +### Step 1: External Resource Evidence +Execute Skill: external-resource-context when external evidence is required. -Run the hearing protocol only when external evidence can change the current adjustment target or verification result. Otherwise continue with the existing repository/UI Spec evidence and record no external references. +Resolve only external evidence that can change the current adjustment target or verification result; use existing access details and ask only for missing decision-relevant inputs. Otherwise continue with the existing repository/UI Spec evidence and record no external references. ### Step 2: Determine the Route and Write Set @@ -99,14 +99,11 @@ Execute Skill: testing-principles before adding or changing tests. Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: - - Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path) - - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) +3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. 5. When the complete adjustment matches the confirmed target, proceed to Step 6. -When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. +When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. ### Step 6: Quality Verification @@ -132,7 +129,7 @@ On continuation, reconstruct retained limitations from the verification trailers ## Completion Criteria -- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] Decision-relevant external evidence was resolved or its exact limitation retained; no record is required when repository/UI Spec evidence suffices - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 1288befe..22f628a4 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -113,7 +113,7 @@ When `adrDecisionPoints` is non-empty: 1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. 2. Collect all returned paths and invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. ## Step 7: Create the Frontend Design Doc @@ -132,6 +132,8 @@ Invoke `dev-workflows-fullstack:technical-designer-frontend` with exactly: The Design Doc owns the full component-to-service implementation and retains all applicable downstream safeguards. +When a backend Design Doc already exists for this feature, pass a distinct `output_path` such as `docs/design/[feature-name]-frontend-design.md`; preserve the backend path as a reference. + ## Step 8: Verify, Review, and Approve Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. diff --git a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md index e66bee40..00ad1f6b 100644 --- a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md @@ -59,7 +59,7 @@ Follow the planning process below: - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner ### Step 3: Work Plan Creation diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index d9e3fec6..e95801f8 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer-frontend result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows-fullstack:code-reviewer` or `dev-workflows-fullstack:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows-fullstack:code-reviewer" -- `description`: "Re-validate frontend implementation review" -- `prompt`: "Re-review the completed frontend implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows-fullstack:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index 1f338e9e..16ee3111 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md @@ -66,7 +66,7 @@ Key points to enforce as the orchestrator runs the flow: - Execute document-reviewer once per Design Doc (separate invocations) - Run design-sync for cross-layer consistency verification - Pass all Design Docs to work-planner (subagent_type: "dev-workflows-fullstack:work-planner") with vertical slicing instruction -- Pass the Work Plan to document-reviewer (`doc_type: WorkPlan`) and request batch approval only after the review passes +- Pass the Work Plan to document-reviewer (`doc_type: WorkPlan`) and request batch approval after Review Resolution converges and governing-source conflicts are resolved ### 4. Bind the Applicable Flow diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index 6df2797f..30c48668 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -104,7 +104,8 @@ After Structural Scale is determined, follow only that scale's applicable path. - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance diff --git a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md index 1bb62109..de30c4a4 100644 --- a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md @@ -53,7 +53,7 @@ Follow the planning process below: ### Step 2: Test Skeleton Generation - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process ### Step 3: Work Plan Creation diff --git a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md index ffc8a10a..eb165c0c 100644 --- a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md @@ -24,18 +24,18 @@ Before the first finding disposition, read `references/review-resolution.md` fro **Execution Protocol**: 1. **Invoke named specialists for deliverable production** — pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") -2. **Process one step at a time**: Execute steps sequentially within each unit (2 → 3 → 4 → 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next +2. **Respect evidence dependencies**: Generation precedes verification and review for each unit; revision reruns the affected checks. Independent units may be scheduled without changing these gates. 3. **Preserve evidence while bridging outputs** — copy the fields required by the next specialist in their declared form; apply Review Resolution before routing any correction At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -**Execution Gate**: Complete Phase 1 before Phase 2. Within each phase, complete one unit's generation, verification, review, and required revision to convergence before starting the next unit. Advance only when the current step's stated output and quality gate are satisfied. At each loop boundary, select the first unit in the current phase's declared order whose Unit Completion conditions are unsatisfied and that is not logged as a generation failure. A document path proves generation only. +**Execution Gate**: Each Design Doc depends on its completed parent PRD and scope mapping. Advance each unit only when its stated evidence and Unit Completion conditions are satisfied; a document path proves generation only. Continue independent units when another has a recorded failure, and report incomplete units explicitly. ## Step 0: Initial Configuration ### 0.1 Scope Confirmation -Use AskUserQuestion to confirm: +Use supplied instructions and repository context first. Ask only for missing choices that materially change scope or execution; retain prior authorization and preferences: 1. **Target path**: Which directory/module to document 2. **Depth**: PRD only, or PRD + Design Docs 3. **Reference Architecture**: layered / mvc / clean / hexagonal / none @@ -85,14 +85,16 @@ prompt: | - At least one unit discovered → proceed - No units discovered → ask user for hints - `$STEP_1_OUTPUT.prdUnits` exists -- All `sourceUnits` across `prdUnits` (flattened, deduplicated) match the set of `discoveredUnits` IDs — no unit missing, no unit duplicated -- Each discovered unit's `unitInventory` has at least one non-empty category (routes, testFiles, or publicExports). Units with all three empty indicate incomplete discovery — re-run scope-discoverer with focus on that unit's `relatedFiles` +- Flatten `sourceUnits` across `prdUnits` without deduplication: every discovered ID occurs exactly once, with no unknown IDs +- Each discovered unit has source evidence and an inventory containing the applicable categories; empty categories are valid, but each unit requires at least one behavior-bearing route, public export, or `otherEntryPoints` item with a defining source location. Resolve a material coverage limitation through targeted discovery; preserve non-blocking limitations. **Human Review Point** (if enabled): Present `$STEP_1_OUTPUT.prdUnits` with their source unit mapping. The user confirms, adjusts grouping, or excludes units from scope. This is the most important review point — incorrect grouping cascades into all downstream documents. ### Step 2-5: Per-Unit Processing -**FOR** each unit in `$STEP_1_OUTPUT.prdUnits` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_1_OUTPUT.prdUnits`: + +Derive `$PRD_UNIT_INVENTORY` by joining this PRD unit's `sourceUnits` to `discoveredUnits[].id` and merging their `unitInventory` categories. Deduplicate the merged inventory by item identity (route method/path/owner, test path, export file/name, other entry-point file/name), preserving source evidence. Use this same baseline for generation and verification. #### Step 2: PRD Generation @@ -110,9 +112,10 @@ prompt: | Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged) Related Files: $PRD_UNIT_COMBINED_RELATED_FILES Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS + Unit Inventory: $PRD_UNIT_INVENTORY Use provided scope as investigation starting point. - If tracing entry points reveals files outside this scope, include them. + Inspect dependencies outside these files only when they establish an in-scope behavior or contract; this does not automatically expand feature scope. Create final version PRD based on thorough code investigation. ``` @@ -131,7 +134,7 @@ prompt: | doc_type: prd document_path: $STEP_2_OUTPUT - unit_inventory: [the current unit's Step 1 unitInventory] + unit_inventory: $PRD_UNIT_INVENTORY ``` `unit_inventory` supplies the completeness baseline while repository evidence supplies the search scope. @@ -181,7 +184,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -202,20 +205,22 @@ Each PRD unit from Phase 1 maps to Design Doc unit(s): - **Standard mode (fullstack=No)**: 1 PRD unit → 1 Design Doc (using technical-designer) - **Fullstack mode (fullstack=Yes)**: 1 PRD unit → 2 Design Docs (technical-designer + technical-designer-frontend) -Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward: +For each PRD unit, join its `sourceUnits` to discovered units and merge their technical evidence and inventory, preserving provenance. Map the result to Design Doc targets, carrying forward: - `technicalProfile.primaryModules` → Primary Files - `technicalProfile.publicInterfaces` → Public Interfaces - `dependencies` → Dependencies - `relatedFiles` → Scope boundary -- `unitInventory` → Unit Inventory (routes, test files, public exports) +- `unitInventory` → Unit Inventory (routes, test files, public exports, other entry points) In fullstack mode, partition each unit inventory by the owning path into backend and frontend target inventories. Assign a shared entry to each Design Doc whose public contract must account for it and record that shared reason; otherwise assign it once. Each Step 7 and Step 8 invocation receives its target's inventory, not the unpartitioned combined unit. +Assign each target a distinct `output_path` before generation. Use `[feature]-design.md` in standard mode and `[feature]-backend-design.md` / `[feature]-frontend-design.md` in fullstack mode. Check existing destinations and preserve unrelated artifacts. + **Store output as**: `$STEP_6_OUTPUT` ### Step 7-10: Per-Unit Processing -**FOR** each unit in `$STEP_6_OUTPUT` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_6_OUTPUT`: #### Step 7: Design Doc Generation @@ -238,10 +243,11 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY + output_path: $DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH - Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports should be accounted for in the Design Doc. + Document current architecture as-is. Use Unit Inventory as a completeness baseline — all inventoried capabilities should be accounted for in the Design Doc. ``` **Store output as**: `$STEP_7_OUTPUT` @@ -265,6 +271,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $BACKEND_UNIT_INVENTORY + output_path: $BACKEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH @@ -289,6 +296,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $FRONTEND_UNIT_INVENTORY + output_path: $FRONTEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH Backend Design Doc: $STEP_7a_OUTPUT @@ -371,7 +379,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -394,4 +402,4 @@ Output summary including: |-------|--------| | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | -| Verification is `inconsistent` or inventory remains unaccounted after correction | Flag for mandatory human review — require explicit human approval | +| Required defect remains after Review Resolution | Report the unit incomplete with evidence. A raw verifier label or a resolved decline creates no extra approval gate; optional human review follows Step 0. | diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index 60fa13cc..21b8410a 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows-fullstack:code-reviewer` or `dev-workflows-fullstack:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows-fullstack:code-reviewer" -- `description`: "Re-validate implementation review" -- `prompt`: "Re-review the completed implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows-fullstack:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md index 253af498..defb3cf7 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -1,6 +1,6 @@ --- name: requirement-convergence -description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from decision-relevant repository evidence. Use when a requirement enters a workflow, before design begins. --- # Requirement Convergence @@ -18,7 +18,7 @@ This skill converges **what to build**. How to build it, and which documents the | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | -| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | +| `cost` | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. diff --git a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md index 9d5cbb91..3e8d0727 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md @@ -29,20 +29,9 @@ An adjacent capability the agent noticed stays out of both `requirements[]` and ## cost -Cost follows structure and count, not behavior, so it is decided from these inputs alone: +Estimate rough lifecycle cost from affected responsibilities, contract consumers, reusable behavior, state/migration needs and existing verification support. Inspect enough representative behavior to decide whether an apparent reuse or structural match actually serves the requirement. Use analyzer evidence when supplied. Stop before implementation-level investigation once further detail cannot change scope, cost band or the user decision. -| Input | How it is obtained | -|-------|--------------------| -| Number and kind of targets to change | Grep/Glob over the affected files | -| Number of boundaries crossed | Affected path composition plus import and caller tracing | -| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | -| Whether persisted state needs converting | Whether a schema or migration path is in the change set | -| Whether verification support already exists | Glob for the area's existing test harness | -| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | - -Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. - -Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. +Record `cost` as one evidence-supported band and its remaining unknowns. When an unresolved condition could raise the band, state that condition and the higher-band consequence in the existing cost evidence so scope confirmation exposes the trade-off. A flow declares `cost` out of scope only where its own steps say so. ## Challenge intensity @@ -51,10 +40,10 @@ The band's only job is to select a row here, so cheap requirements stay cheap to | Band | Meaning | Challenge | |------|---------|-----------| | `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | -| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | -| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | +| `medium` | Reverting would touch other work | Present cost and a lower-cost alternative when a materially distinct sufficient option exists | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off; obtain a user decision when a required outcome, explicit constraint or irreversible-action authority must change | -Report an unknown that would move the band up as a blocking question rather than assuming the lower band. +Resolve repository-answerable uncertainty locally. Ask the user only when a remaining unknown changes required scope, constraints or authority; otherwise record its cost effect and keep independent work moving. ## Solution-in-disguise test diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 555c3632..3303e4f7 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -156,7 +156,7 @@ Rules: - When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` - When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported - Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add only their named UI or layer artifact paths +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -204,7 +204,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. + +When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -244,7 +246,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance @@ -282,7 +285,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-03b: applied design-evidence finding → technical-designer - Invoke the owning designer as a fresh `update` call with the existing Design Doc path and complete `correction_findings` objects copied verbatim with only their `apply` dispositions added. - The existing artifact carries approved requirements, accepted decisions, prior evidence, and unaffected design context. Keep the handoff limited to the artifact path and unchanged applied findings. -- The designer applies its review-triggered self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. +- The designer applies its review-triggered bounded self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. @@ -302,8 +305,8 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner - Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. -- When it returns `value_input_required`, ask once for each listed missing fact, preserve the answer verbatim as `test_value_context`, and reinvoke. The generator applies supplied facts, retains every remaining value as `unknown`, chooses from the available requirement and repository evidence, and continues to its normal completed result. -- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, confirm from the Design Doc that no accepted proof obligation requires that boundary, and return an uncovered obligation to the generator for completion. +- Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. +- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. - Route an unexpected integration generation failure as incomplete generator work. A validated null E2E lane is complete. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index 289f8bf3..2967d10c 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -77,7 +77,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. - Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per owning-designer invocation serially, and repeats the complete batch review; `rejected` resolves the governing-source conflict before another review. -- Obtain one user approval after a `pass` review, then set every approved ADR to `Accepted`. +- Obtain one user approval after Review Resolution converges and governing-source conflicts are resolved, then set every approved ADR to `Accepted`. - An empty batch proceeds directly to both Design Docs. ## Layer Design Context @@ -88,6 +88,7 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-backend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -98,6 +99,7 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-frontend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -117,7 +119,7 @@ After both document reviews permit approval, invoke design-sync with `source_des ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for `value_input_required` and its unknown-value continuation before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md index 8da4072d..078058c3 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md @@ -19,7 +19,7 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. For code-verifier with `unit_inventory`, its full current-document inventory accounting still applies. A decline-only result is complete. ## 1. Assess Every Finding @@ -58,9 +58,9 @@ Select the existing correction owner from the accepted state each finding requir For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. -For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. +For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its review-triggered bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. -For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. +For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. For each ID, preserve the original finding claim and basis verbatim in `evidence`, alongside the correction diff or paths. The correction assessment covers exactly every received item. The reviewer completes that scope and then: @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/dev-workflows-fullstack/skills/testing-principles/SKILL.md b/dev-workflows-fullstack/skills/testing-principles/SKILL.md index df9c948f..72579f85 100644 --- a/dev-workflows-fullstack/skills/testing-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/testing-principles/SKILL.md @@ -11,6 +11,7 @@ Tests here guarantee accepted behavior, and the next agent reads every existing - Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules. - Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere. +- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary. - Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself. - Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it. diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 4ead3b9a..97f69de4 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.1", + "version": "0.29.2", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index c0100cb8..a8ffc948 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -1,6 +1,6 @@ --- name: acceptance-test-generator -description: Generates integration/E2E test skeletons from Design Doc ACs using ROI-based selection and journey-based E2E reservation. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. +description: Generates integration/E2E test skeletons from Design Doc ACs using required proof boundaries and existing coverage. Use when Design Doc is complete and test design is needed, or when "test skeleton/AC/acceptance criteria" is mentioned. Behavior-first approach for minimal tests with maximum coverage. tools: Read, Write, Edit, Glob, LS, Grep skills: - testing-principles @@ -9,277 +9,62 @@ skills: - llm-friendly-context --- -You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation. +You generate comment-only integration/E2E test skeletons for required proof that cannot be supplied more cheaply. Apply testing-principles for proof selection and safety, integration-e2e-testing for skeleton and lane contracts, and repository conventions for placement. -Operates in an independent context, executing autonomously until task completion. +## Inputs -## Execution Gate +- **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. +- **ui_spec**: Optional UI Spec whose interactions constrain those criteria. +- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. -### Implementation Approach Compliance -- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection) -- **Contract Safety**: Apply the testing-principles skill mock creation and contract definition rules to every generated skeleton +## Selection -## Input Parameters +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. +3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. -- **design_docs**: Required list of one or more Design Doc paths. These provide acceptance criteria and Test Boundaries decisions. -- **ui_spec**: Optional UI Spec path. Use its screen transitions, state x display matrix, and interaction definitions as additional E2E candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology. -- **confirmed_requirement_context**: Optional approved PRD path or unchanged confirmed convergence record. When absent, resolve the carrier from the Design Docs' Requirement Convergence sections when possible. -- **test_value_context**: Optional verbatim user response returned after `value_input_required`. Apply supplied Business Value, User Frequency, and Legal Requirement facts; its presence marks the single value-input round complete. +## Skeleton Contract -Workflow callers use these canonical names. Accept equivalent Design Doc and UI Spec labels, individual paths, and concise prose forms, then normalize them into the fields above. +Use the repository's language, directory and naming conventions. Each lane has a separate file; preserve existing content and add only non-duplicated obligations. Follow Design Doc patterns where they determine the actual consumer contract. -## Test Type Definition +A skeleton is committed before implementation, so its committed form contains only comments: no imports of absent modules or executable test-runner blocks. Implementers add imports, setup and assertions in the earliest task where the boundary is executable. Keep static gates valid at the skeleton stage without claiming that comments prove behavior. -Test type definitions, budgets, and ROI calculations are specified in **integration-e2e-testing skill**. +Each selected test records: -## 4-Phase Generation Process +- original AC text and source Design Doc (or UI journey plus its governing AC); +- trigger and observable result; +- `@lane`, `@dependency` using integration-e2e-testing annotations; +- selection evidence: uncovered claim and why existing or cheaper proof is insufficient; +- primary failure mode: the regression this test must detect; +- proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; +- a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. -### Phase 1: AC Validation (Behavior-First Filtering) +Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. -**EARS Format Detection**: Determine test type from EARS keywords in AC: -| Keyword | Test Type | Generation Approach | -|---------|-----------|---------------------| -| **When** | Event-driven test | Trigger event → verify outcome | -| **While** | State condition test | Setup state → verify behavior | -| **If-then** | Branch coverage test | Condition true/false → verify both paths | -| (none) | Basic functionality test | Direct invocation → verify result | +## Output -**For each AC, apply these mandatory checks**: - -| Check | Question | Action if NO | Skip Reason | -|-------|----------|--------------|-------------| -| **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **Upstream Scope** | In the integration-e2e-testing Behavior-First Include list? | Skip | [OUT_OF_SCOPE] | - -**AC Selection Criteria**: Apply the Include and Redirect lists in the integration-e2e-testing skill's Behavior-First Principle. - -**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section: -- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate -- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required -- Record the mock/real decision in test skeleton annotations alongside existing metadata - -**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists) - -### Phase 2: Candidate Enumeration (Two-Pass #1) - -For each valid AC from Phase 1: - -1. **Generate test candidates**: - - Happy path (1 test mandatory) - - Error handling (only if user-visible error) - - Edge cases (only if high business impact) - - Boundary path (behavior-changing AC only): when the AC can hold on the main path while a distinct branch, state, input class, lifecycle step, or fallback regresses, capture that boundary as a proof obligation so the test exercises it - -2. **Classify test level**: - - Integration test candidate (feature-level interaction) - - E2E test candidate (complete user journey) - -3. **Annotate metadata**: - - Record one source for Business Value, User Frequency, Legal Requirement, and Defect Detection, then assign the exact value or `unknown` using the preloaded integration-e2e-testing skill - - Treat requirement/user/business evidence as the source for value and frequency, accepted obligations or a checked governing source with no accepted obligation as the source for Legal Requirement, and boundary plus existing-test evidence as the source for Defect Detection - -**Output**: Candidate pool with ROI metadata - -### Phase 3: ROI-Based Selection and Lane Assignment (Two-Pass #2) - -ROI calculation formula and cost table are defined in **integration-e2e-testing skill**. Lane definitions and selection rules are also in that skill. - -**Selection Algorithm**: - -1. **Deduplication Check**: - ``` - Grep existing tests for same behavior pattern - If covered by existing test → Remove candidate - ``` -2. **Push-Down Analysis**: - ``` - Can this be unit-tested? → Remove from integration/E2E pool - Already integration-tested AND verifiable in-process? → Remove from E2E pool - ``` -3. **Lane assignment** (E2E candidates only): - - Default to `fixture-e2e` for any UI journey verifiable with mocked backend / fixture-driven state - - Promote to `service-integration-e2e` only when the verification depends on real cross-service behavior. A candidate qualifies for `service-integration-e2e` when ANY of the following must be asserted: - - Data persists across a real DB write (e.g., row inserted/updated in the actual database under test) - - A downstream service receives a real event/message (e.g., topic publish, queue enqueue, webhook call) - - An external service receives a real API call with the expected payload - - Transactional consistency across services (e.g., two-phase commit, saga compensation) -4. **Resolve decision-relevant ROI inputs**: - - On the surviving lane-assigned pool, determine whether each `unknown` can change ranking, a lane threshold, or budget selection - - Resolve Defect Detection from the Design Doc proof boundaries and existing-test search; continue repository investigation when that evidence is incomplete - - When `test_value_context` is absent and an unknown Business Value, User Frequency, or Legal Requirement can change selection, return `status: "value_input_required"` before writing skeletons, naming only the missing inputs and decision effects - - When `test_value_context` is present, apply the supplied facts, retain every remaining decision-relevant value as `unknown` with its numeric score unset, and continue with the integration-e2e-testing Unknown-Value Ordering - - When it cannot, mark it `not_decision_relevant` and retain the invariant selection basis without fabricating a score -5. **Calculate ROI** for each fully resolved candidate; keep unresolved decision-relevant inputs unknown -6. **Sort within each lane** using ROI and its tie-break order for fully scored candidates, or Unknown-Value Ordering for affected candidates. Phase 4 processes that single ranked list. - -**Output**: Ranked, deduplicated candidate list with lane assigned per E2E candidate. - -### Phase 4: Budget Enforcement - -**Standard Budgets per Input Design Doc**: -- **Integration Tests**: MAX 3 tests -- **fixture-e2e**: MAX 3 tests; additional slots require ROI ≥ 20. When the input Design Doc contains a **user-facing** multi-step user journey, the highest-ROI journey candidate is reserved (emitted regardless of ROI) -- **service-integration-e2e**: MAX 1-2 tests, composed of: - - 1 reserved slot (emitted regardless of ROI) when the journey's correctness depends on real cross-service behavior that fixture-e2e cannot verify - - Up to 1 additional slot requiring ROI > 50 - -**Selection Algorithm**: - -``` -1. Reserve fixture-e2e slot: - IF the input Design Doc contains a user-facing multi-step user journey - THEN reserve 1 fixture-e2e slot for the highest-ROI journey candidate - -2. Reserve service-integration-e2e slot (only if needed): - IF the reserved journey's verification requires ANY of: - - data persists across a real DB write - - downstream service receives a real event/message - - external service receives a real API call with expected payload - - transactional consistency across services - THEN reserve 1 service-integration-e2e slot for that journey - -3. Walk the candidate list (already sorted by ROI within each lane in Phase 3 step 6) - and select within budget: - - Integration: Pick top 3 highest-ROI - - fixture-e2e (additional beyond reserved): Pick up to remaining budget IF ROI ≥ 20 - - service-integration-e2e (additional beyond reserved): Pick up to 1 more IF ROI > 50 - - Leave budget intentionally unfilled when no remaining candidate clears the lane's threshold. - -4. **Exception review**: - - Exceed a standard budget only when an accepted requirement or a distinct failure mode remains unproved by the selected set - - For each exception, record the requirement/failure mode and why an existing selected test cannot absorb it without obscuring its proof obligation - - A lower score alone is not an exception; below-threshold selection needs the same requirement/failure-mode evidence -``` - -**Output**: Final test set with any threshold/budget exceptions identified - -## Output Format - -### Test Skeleton Shape - -Use the project's comment syntax (`//`, `#`, etc.). Preserve AC text (or user journey description for E2E), ROI breakdown or invariant selection basis, ROI evidence sources, lane, dependency, complexity, verification points, expected results, pass criteria, primary failure mode, and proof obligation. When selection exceeds a standard budget or threshold, add `Selection exception:` with the accepted requirement or distinct uncovered failure mode and the non-consolidation reason. - -A skeleton is committed before its implementation exists, so its committed form contains **only comments**: no import of a not-yet-existing module and no test-runner syntax (e.g. `describe`/`it`) that the project's static gates evaluate. This keeps a freshly committed skeleton green under the project's standard static gates (typecheck, lint, build), so they do not fail on a reference to not-yet-implemented code. The implementing task adds the executable imports, runner blocks, and assertions alongside the implementation, keeping the Red→Green transition within a single task/commit. - -``` -// [Feature Name] [integration|fixture-e2e|service-integration-e2e] Test - Design Doc: [filename] -// Generated: [date] | Budget Used: [integration], [fixture-e2e], [service-e2e] -// -// AC1: "After successful payment, order is created and persisted" -// ROI: 120 (BV:10 × Freq:10 + Legal:true×10 + Defect:10) -// ROI evidence: BV=PRD §Success Criteria; Freq=PRD §Primary User Journey; Legal=accepted payment contract; Defect=Design Doc §Test Boundaries + existing test search -// Behavior: User completes payment → Order created in DB + Payment recorded -// @category: core-functionality -// @lane: integration -// @dependency: PaymentService, OrderRepository, Database -// @complexity: high -// Primary failure mode: payment succeeds but the order row is absent or unpersisted -// Proof obligation: the order is persisted only after a successful payment; the external payment gateway is the only boundary that may be mocked -// Verification points / expected results / pass criteria: [enumerate the observable checks the implemented test must assert] -``` - -### Generation Report +Return a selection explanation followed by the result JSON. Explain empty lanes and unresolved limitations according to Selection. ```json { "status": "completed", - "feature": "payment", + "feature": "feature name", "generatedFiles": { - "integration": "tests/payment.int.test.[ext]", - "fixtureE2e": "tests/payment.fixture.e2e.test.[ext]", - "serviceE2e": null + "integration": "path or null", + "fixtureE2e": "path or null", + "serviceE2e": "path or null" } } ``` -**Contract**: a `completed` result always contains `generatedFiles.integration`, `generatedFiles.fixtureE2e`, and `generatedFiles.serviceE2e`. Value is a file path string when that lane emitted, `null` when it did not. The orchestrator confirms an empty lane against the Design Doc's accepted proof obligations; the selection evidence for every emitted skeleton stays in that skeleton's metadata. - -Describe the run's filtering and selection outcome in the surrounding message. Whenever a lane emits nothing, name the removed candidates and the filter that removed each one — the JSON carries paths only. - -**When a decision-relevant value input is missing:** -```json -{ - "status": "value_input_required", - "missingValueInputs": [ - {"candidate": "AC-002 payment retry", "input": "User Frequency", "evidenceChecked": ["PRD §User Stories", "Design Doc §Requirement Convergence"], "decisionEffect": "Determines whether fixture-e2e clears ROI 20"} - ], - "acceptedSources": ["approved PRD or confirmed requirement context", "accepted contractual/legal obligation", "verbatim user-confirmed test_value_context"] -} -``` - -Return this status before creating or modifying skeleton files. The caller supplies its single response as `test_value_context` and reinvokes the generator. Apply supplied facts, preserve every remaining decision-relevant value as `unknown`, use Unknown-Value Ordering, and return the normal completed result. Record the evidence checked, ordering basis, and selection effect in generated skeleton metadata. - -## Test Meta Information Assignment - -Each test case MUST have the following standard annotations for test implementation planning: - -- **@category**: core-functionality | integration | edge-case | ux | fixture-e2e | service-integration-e2e -- **@lane**: integration | fixture-e2e | service-integration-e2e -- **@dependency**: none | [component names] | full-ui (mocked backend) | full-system -- **@complexity**: low | medium | high -- **Primary failure mode**: the specific regression that turns this test red — the behavior the AC promises and would break -- **Proof obligation**: what the implemented test must assert to prove the claim — the boundary to traverse, the observable state before/after for state-changing ACs, and which boundaries may be mocked and why. For behavior-changing ACs, name the boundary path (branch, state, input class, lifecycle step, or fallback) the test must traverse when the main path alone would stay green through the regression. Phrase it as design intent describing what to assert; executable assertions and mock setup are outside this output - -These annotations drive test planning and prioritization. The `@lane` annotation is the source of truth for budget accounting and CI gating. The primary failure mode and proof obligation preserve the proof contract in the skeleton for implementation and review. - -## Constraints and Quality Standards - -**Mandatory Compliance**: -- Output test skeletons only: verification points, expected results, pass criteria, primary failure mode, and proof obligation. - Background: Skeletons are comment-based design information, not executable code. -- Clearly state verification points, expected results, and pass criteria for each test -- Preserve original AC statements in comments (ensure traceability) -- Preserve the evidence source or `not_decision_relevant` basis for every ROI input; assign no numeric value to an unknown input -- Stay within test budget; report if budget insufficient for critical tests - -**Quality Standards**: -- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slots emitted regardless of ROI + fixture-e2e additional ROI ≥ 20 + service-integration-e2e additional ROI > 50) -- Apply behavior-first filtering strictly -- Eliminate duplicate coverage (use Grep to check existing tests) -- Clarify dependencies explicitly -- Logical test execution order - -## Exception Handling and Stop Conditions - -### Auto-processable -- **Directory Absent**: Auto-create appropriate directory following detected test structure -- **No Integration Candidates**: Valid outcome - report "No Integration candidates remained after Phase 1 filtering, deduplication, and push-down analysis" -- **No E2E Tests (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; E2E tests not applicable" -- **Budget insufficient for a critical user journey (ROI > 90)**: Exceed the lane budget per the integration-e2e-testing skill's budget rule when the journey's failure mode cannot be proved by a selected test, and annotate the exception and why consolidation cannot cover it -- **No E2E test emitted after budget enforcement, but the input Design Doc contains a user-facing multi-step journey**: Report the journey, every candidate evaluated with its ROI score, and the filter that removed each one, then continue. (This case arises only when the reserved slot in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering.) -- **Every AC filtered out, leaving no generated test**: Valid outcome - return the empty result and report the filter that removed each AC -- **Multiple interpretations possible but minor impact**: Adopt the interpretation and note it in the report -- **Missing value that cannot change selection**: Record `not_decision_relevant` with the invariant selection basis and continue -- **Decision-relevant value remains unknown after the value-input round**: Preserve `unknown`, apply Unknown-Value Ordering, record its selection effect, and continue - -### Stop Conditions - -These two cases end generation and hand control back; every other case above completes with a recorded result. - -1. **Required input absent**: AC absent or Design Doc absent → terminate and name the missing input -2. **Decision input required**: An unknown Business Value, User Frequency, or Legal Requirement can change ranking, threshold, or budget selection → Return `value_input_required` when `test_value_context` is absent; after that input round, preserve remaining unknowns and continue with Unknown-Value Ordering - -## Technical Specifications - -**Project Adaptation**: -- Framework/Language: Auto-detect from existing test files -- Placement: Identify test directory with project-specific patterns using Glob -- Naming: Follow existing file naming conventions -- Output: Test skeletons only (see Constraints section above for boundary) - -**File Operations**: -- Existing files: Append to end, prevent duplication (check with Grep) -- New creation: Follow detected structure, include generation report header +Each lane value is an existing file path when generated, otherwise JSON `null`. Selection evidence stays in each skeleton; the parent checks empty lanes against accepted proof obligations. When blocked, return `{"status":"blocked","reason":"exact missing prerequisite and affected claim"}` instead of an invented completed result. -## Quality Assurance Checkpoints +## Completion Check -- Design Doc exists and contains ACs -- AC measurability confirmed -- Existing coverage checked with Grep -- Behavior-first filtering, ROI ranking, and budget enforcement completed -- Dependency names verified against Design Doc / UI Spec / code, or marked external -- Integration, fixture-e2e, and service-integration-e2e outputs are separate files when generated -- Generation report includes all required keys +- Every required integration/E2E boundary has sufficient existing proof, a selected skeleton, or an explicit limitation; unresolved coverage is not a completed claim. +- Every new skeleton is necessary for its observable boundary; repeated proof is consolidated. +- Required real dependencies remain real in the proof contract. +- Skeletons contain only comments and preserve original criteria, dependencies and exact paths for planning. +- Output includes all three lane keys when completed. diff --git a/dev-workflows/agents/code-verifier.md b/dev-workflows/agents/code-verifier.md index 9cb87f39..a114b2b7 100644 --- a/dev-workflows/agents/code-verifier.md +++ b/dev-workflows/agents/code-verifier.md @@ -16,8 +16,8 @@ Your discrepancies are independent evidence for orchestrator Review Resolution. - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path -- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` -- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead +- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, `publicExports`, and optional `otherEntryPoints` (`{ name, file }` items; absent means empty) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -35,7 +35,7 @@ First identify the document claims that control scope, feasibility, implementati For a future-state PRD or Design Doc, planned behavior is intent rather than a code gap. Verify its current-state premises and feasibility before implementation; verify its implementation only in post-implementation context. -For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, and test mappings. An item may be excluded only when the document boundary and repository evidence justify it. +For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, other inventoried capabilities, and test mappings. Verify `otherEntryPoints` against their defining source locations and check that the document accounts for their observable behavior. An item may be excluded only when the document boundary and repository evidence justify it. Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. @@ -43,7 +43,7 @@ Stop expanding the search when additional evidence cannot change a discrepancy o ## Rerun Boundary -`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. +When `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link and carry forward repository evidence only where its unchanged basis is established. With `unit_inventory`, recheck every supplied item against the current document and recompute complete coverage accounting on every rerun; reuse still-valid code evidence instead of repeating repository investigation. When only paths are supplied, inspect their current contents to establish the affected claims. Report any current inventory omission; otherwise emit a new discrepancy only when the correction caused it. ## Classification @@ -81,12 +81,15 @@ When `unit_inventory` is supplied, replace `inventoryCoverage: null` with this o { "routes": {"inputCount": 3, "accountedCount": 2, "excluded": [{"item": "route", "evidence": "path:line and boundary reason"}], "unaccounted": []}, "testFiles": {"inputCount": 2, "accountedCount": 2, "excluded": [], "unaccounted": []}, - "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []} + "publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []}, + "otherEntryPoints": {"inputCount": 0, "accountedCount": 0, "excluded": [], "unaccounted": []} } ``` For each inventory category, `accountedCount + excluded.length + unaccounted.length` equals `inputCount`. Report every unaccounted item as one cause-grouped `gap` discrepancy. +When routes, public exports, and other entry points are all empty, return `blocked`: the supplied inventory has no behavior baseline, even if test files exist or zero counts balance. + An unaccounted inventory item makes `consistent` invalid; use at least `needs_review`. When the supplied inventory cannot be parsed or the counts cannot be made balanced from it, use `blocked` and state the exact input defect. Status rules: diff --git a/dev-workflows/agents/design-sync.md b/dev-workflows/agents/design-sync.md index 5ea6a3f9..ceaad0c5 100644 --- a/dev-workflows/agents/design-sync.md +++ b/dev-workflows/agents/design-sync.md @@ -12,34 +12,15 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Detection Criteria (The Only Rule) +## Detection Boundary -**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. +Detect contradictory obligations for the same shared entity, contract or integration boundary. Establish identity from owning service/module, referenced definition, explicit alias and applicability (version, mode or state). Equal strings alone do not identify a shared entity: local AC IDs, fact IDs and common type names may repeat across unrelated documents. -**Rationale**: Return high-recall conflict candidates; filtering occurs after this result. Prioritize catching real conflicts over avoiding false positives. +Report a material conflict only when the two obligations cannot both hold under the same applicable conditions. Different versions, scoped overrides and complementary caller/implementation descriptions may be compatible. Use `confidence: high` with `match_basis: exact_string|explicit_alias` only when the shared identity and contradiction are established. Use `confidence: medium` with `match_basis: same_endpoint_role|same_integration_role|same_ac_slot` when structural evidence links a material candidate but identity remains uncertain; state the exact uncertainty in `reason`. -### Match Basis Rules +`same_endpoint_role` links the same service/module and HTTP method or route role; `same_integration_role` links the same owning service and flow stage; `same_ac_slot` links the same user trigger and expected outcome category. In each case, cite the shared context rather than matching a local identifier alone. -Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence. - -**high confidence** (confirmed conflict): - -| match_basis | Definition | -|-------------|-----------| -| `exact_string` | Identical identifier string in both documents | -| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other | - -**medium confidence** (candidate conflict — requires `reason` with structural evidence): - -| match_basis | Structural evidence required | Example | -|-------------|---------------------------|---------| -| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService | -| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point | -| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements | - -**Matching scope**: -- Match across any section — section name differences are irrelevant -- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope +The source document selects the comparison scope, not the winning value. Governing requirements, accepted decisions and authoritative shared definitions determine precedence. When they do not resolve the conflict, report the required evidence rather than choosing the newer file. ## Responsibilities @@ -60,13 +41,13 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters -- **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **source_design**: Path to the newly created/updated Design Doc (comparison starting point) - **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition **When target Design Docs count is 0** (no files other than source_design in docs/design/): -- Skip investigation and immediately terminate with NO_CONFLICTS status +- Return `SKIPPED` with the reason that no comparison target exists - Reason: Consistency verification is unnecessary when there is no comparison target ## Workflow @@ -85,7 +66,7 @@ Read the Design Doc specified in arguments and extract: - **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths - **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations) - **Acceptance criteria**: Specific conditions for functional requirements -- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value serves as the primary identifier for cross-document matching. `evidence` is supporting context only. +- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. Match the fact's source, owning boundary and applicability; a local `fact_id` alone is insufficient. **Extraction Output** (per item): ```yaml @@ -95,27 +76,25 @@ Read the Design Doc specified in arguments and extract: context: "[how it is used: definition / reference / constraint]" ``` -### 2. Survey All Design Docs +### 2. Locate Relevant Design Docs -- Search docs/design/*.md (excluding template) -- Read all files except source_design -- Detect conflict patterns +Use the source's shared contracts, references and owning entities to search candidate documents. Read the matching sections and enough context to establish identity and applicability. Include every document whose shared obligation could materially conflict; stop expansion when remaining documents cannot affect that judgment. Record unavailable relevant evidence. ### 3. Conflict Classification and Severity Assessment **Conflict Detection Process**: 1. Extract each item from source file using extraction output format -2. For each extracted item, search other files for matches using Match Basis Rules -3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason` +2. For each extracted item, search other files for matches using Detection Boundary +3. Record a conflict when the same applicable shared obligation has incompatible values, definitions or referents. Include `match_basis`, `confidence`, and `reason` 4. Items not in source file are not detection targets | Conflict Type | Criteria | Severity | |--------------|----------|----------| | **Type definition mismatch** | Same type/interface name, different properties or field types | critical | | **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical | -| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | +| **Disposition conflict** | Same sourced fact and applicable boundary, incompatible `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical | | **Numeric parameter mismatch** | Same config key, different value | high | -| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high | +| **Acceptance criteria conflict** | Same scoped obligation, incompatible conditions or thresholds | high | | **Term definition mismatch** | Same term string, different definition text | medium | ### 4. Decision Flow @@ -123,7 +102,7 @@ Read the Design Doc specified in arguments and extract: ``` Item extracted from source file? ├─ No → Not a detection target (end) - └─ Yes → Match found in other files via Match Basis Rules? + └─ Yes → Match found in other files via Detection Boundary? ├─ No → No comparison target (end) └─ Yes → Value/definition/referent differs? ├─ No → No conflict (end) @@ -155,7 +134,7 @@ total_conflicts: [total number of conflicts detected] critical: [critical count] high: [high count] medium: [medium count] -sync_status: [CONFLICTS_FOUND | NO_CONFLICTS] +sync_status: [CONFLICTS_FOUND | NO_CONFLICTS | SKIPPED] [/SUMMARY] [CONFIRMED_CONFLICTS] @@ -173,7 +152,7 @@ target_location: [section/line] target_value: | [conflicting content] recommendation: | - [Recommend unifying to source file's value] + [Smallest correction supported by governing evidence, or exact evidence needed to resolve precedence] [/CONFIRMED_CONFLICTS] [CANDIDATE_CONFLICTS] @@ -214,90 +193,12 @@ suggested_action: | [/RECOMMENDATIONS] ``` -## Detection Pattern Examples - -### High confidence: exact_string (type definition, cross-section) -``` -// Source Design Doc — Section: "Data Contracts" -OrderItem { - quantity: number - unitPrice: number -} - -// Other Design Doc — Section: "API Response Schema" -OrderItem { - quantity: string // different type - unitPrice: number - discount: number // extra property -} -``` -→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant. - -### High confidence: exact_string (path identifier) -``` -# Source Design Doc — Section: "Endpoints" -POST /api/orders/submit → handler: OrderController.submit - -# Other Design Doc — Section: "Integration Points" -POST /api/orders/submit → handler: OrderService.createOrder -``` -→ confidence: high, match_basis: exact_string. Same path, different handler. - -### High confidence: exact_string (numeric parameter) -``` -# Source Design Doc -Max retry count: 3 - -# Other Design Doc -Max retry count: 5 -``` - -### Medium confidence: same_endpoint_role -``` -# Source Design Doc -POST /api/v2/orders → handler: OrderController.create - -# Other Design Doc -POST /api/v1/orders → handler: OrderController.submit -``` -→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method." - -### Medium confidence: same_integration_role -``` -# Source Design Doc — Section: "Authentication Flow" -Entry point: AuthService.authenticate(credentials) → Session - -# Other Design Doc — Section: "Login Integration" -Entry point: AuthService.login(email, password) → Token -``` -→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types." - -### Medium confidence: same_ac_slot -``` -# Source Design Doc — AC-003 -When user submits valid credentials, the system shall create a session with 30-minute expiry - -# Other Design Doc — AC-012 -When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry -``` -→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)." - -### Not reported (no structural evidence) -``` -# Source Design Doc -Endpoint: POST /api/users/register - -# Other Design Doc -Endpoint: POST /api/accounts/signup -``` -→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence. - ## Quality Checklist - [ ] Correctly read source_design -- [ ] Surveyed all Design Docs (excluding template) +- [ ] Accounted for documents sharing the source's affected contracts and recorded material access limitations - [ ] Extracted items using extraction output format -- [ ] Applied Match Basis Rules across all sections +- [ ] Applied Detection Boundary across all sections - [ ] Every detected conflict includes confidence and match_basis - [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis - [ ] Every medium-confidence conflict includes structural evidence in reason field @@ -307,11 +208,11 @@ Endpoint: POST /api/accounts/signup ## Error Handling - **source_design not found**: Output error message and terminate -- **No target Design Docs found**: Complete normally with NO_CONFLICTS status +- **No target Design Docs found**: Complete normally with SKIPPED status - **File read failure**: Skip the file and note it in the report ## Completion Criteria -- All target files have been read +- All relevant shared obligations have been compared or an exact evidence limitation reported - Structured markdown output completed - All quality checklist items verified diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 9e3c61e3..5f39881d 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -113,8 +113,8 @@ For `prior_feedback`, the received items and the boundaries their corrections ch ## Decision -- `pass`: `issues` is empty. -- `needs_revision`: One or more issues can be repaired inside approved scope. +- `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. +- `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. - `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows/agents/integration-test-reviewer.md b/dev-workflows/agents/integration-test-reviewer.md index ea6c54fc..91a198ff 100644 --- a/dev-workflows/agents/integration-test-reviewer.md +++ b/dev-workflows/agents/integration-test-reviewer.md @@ -41,7 +41,6 @@ For the `skeleton` basis, extract the following comment patterns from the change Annotation patterns (comment syntax varies by project language): - `AC:` → Original acceptance criteria - `Behavior:` → Trigger → Process → Observable Result -- `@category:` → Test classification - `@dependency:` → Dependencies - `Verification items:` → Expected verification items (if present) diff --git a/dev-workflows/agents/investigator.md b/dev-workflows/agents/investigator.md index c1260fbe..38169c72 100644 --- a/dev-workflows/agents/investigator.md +++ b/dev-workflows/agents/investigator.md @@ -42,16 +42,16 @@ Solution derivation is out of scope for this agent. ### Step 2: Information Collection -For each source type below, perform the specified minimum investigation. Record findings even when empty ("checked [source], no relevant findings"). +Choose sources that can establish or contradict the supported causes and scope coverage. The table is a set of investigation cues, not a source quota. Record evidence used and material access limitations. -| Source | Minimum Investigation Action | +| Source | When it informs the diagnosis | |--------|------------------------------| | Code | Read files directly related to the phenomenon. Grep for error messages, function names, and class names mentioned in the problem report | | git history | Trace affected history far enough to identify the comparison baseline and changes that could alter the phenomenon. For change failures, compare the evidenced working and broken states | | Dependencies | Check package manifest for relevant packages. If version mismatch suspected: read changelog | | Configuration | Read config files in the affected area. Grep for relevant config keys across the project | | Design Doc/ADR | Glob for `docs/design/*` and `docs/adr/*` matching the feature area. Read if found | -| External (WebSearch) | Search official documentation for the primary technology involved. Search for error messages if present | +| External (WebSearch) | Consult authoritative documentation when unresolved technology behavior or version compatibility can change a cause judgment | **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values) @@ -210,7 +210,7 @@ Before output, account for every diagnosis-scope item as investigated, excluded - [ ] Determined problem type and executed diff analysis for change failures - [ ] Accounted for every diagnosis-scope item and included newly discovered areas only when they satisfy the envelope and can change causes, coverage, or counter-evidence - [ ] Mapped execution paths for each symptom (pathMap), including main path and symptom-reachable branches -- [ ] Investigated each source type from the information collection table (code, git history, dependencies, configuration, docs, external). Each source has a recorded finding or "no relevant findings" +- [ ] Evidence supports or contradicts each cause and accounts for the diagnosis scope; source selection follows the relevant uncertainty rather than a quota - [ ] Checked all nodes on mapped paths for faults (not just until the first fault was found) - [ ] Each failure point has: location, upstreamDependency, symptomExplained, causalChain (reaching a stop condition), checkStatus, evidence, comparisonAnalysis - [ ] Determined impactScope per failure point diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index 8ac6f213..04010989 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -54,8 +54,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **Reverse Engineering Information** (reverse-engineer mode only): - Target feature file paths (multiple allowed) - - Summary of modifications - - Description of impact scope + - Feature, Description, Related Files, Entry Points + - Unit Inventory when scope discovery has already supplied a baseline + - External Scope Provided: whether to reuse that boundary ## PRD Output Format @@ -117,9 +118,8 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Set specific numerical targets for quantitative metrics -- Specify measurement methods -- Enable comparison with baseline +- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check - Include all stakeholder perspectives @@ -146,7 +146,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does - [ ] Are material relationships clear in prose, a compact table, or a Mermaid diagram where needed? - [ ] **Content is limited to 'what to build' (no implementation phases or work plans)** - [ ] **For UI features: Are accessibility requirements documented?** -- [ ] **For UI features: Are UI quality metrics defined (completion rate, error recovery, a11y targets)?** +- [ ] **For UI features: Are sourced quality requirements and their observable proof represented?** ## Update Mode Operation @@ -166,9 +166,9 @@ Mode for extracting specifications from existing implementation to create PRD. U ### External Scope Handling When `External Scope Provided: true` is specified: -- Skip independent scope discovery (Step 1) +- Reuse the supplied scope and Unit Inventory instead of repeating discovery - Use provided scope data as **investigation starting point**: Feature, Description, Related Files, Entry Points -- If entry point tracing reveals files/routes outside provided scope that are directly called from entry points, **include them** and report as scope expansion in output +- Inspect an outside dependency when it establishes an in-scope behavior or contract. Expand documented feature scope only when evidence shows the original boundary omitted part of that same capability; report the reason. When external scope is NOT provided: - Execute full scope discovery independently @@ -195,52 +195,18 @@ Before documenting any claim, assess confidence level: - Prioritize Verified claims in core requirements - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous -### Reverse PRD Investigation Protocol - -**Step 1: Route & Entry Point Enumeration** (even when External Scope Provided) -- Grep for all route/endpoint definitions in the provided Related Files -- Record EACH route: HTTP method, path, handler, middleware — as written in code -- This becomes the authoritative route list for the PRD - -**Step 2: Entry Point Tracing** -For each entry point / handler identified in Step 1: -1. Read the handler/controller file -2. For each function/service called from the handler: - - Read the function **implementation** (not just the call site) - - Record: function name, file path, key behavior, parameters -3. For each helper/utility function called within services: - - Read the helper implementation - - Record: actual behavior based on code reading - -**Step 3: Data Model Investigation** -For each data type/schema referenced in the traced code: -1. Read the type definition / schema / migration file -2. Record: field names, types, nullable markers, validation rules — AS WRITTEN IN CODE -3. For enum/constant definitions: record ALL values (count them explicitly) - -**Step 4: Test File Discovery** -- Glob for test files matching the feature area (common conventions: `*test*`, `*spec*`, `*Test*`) -- For each test file found: Read it and record test case names and what behavior they verify -- For handlers/services with no test files found via Glob: record as "no tests found" - -**Step 5: Role & Permission Discovery** -- Grep for middleware, guard, role-check patterns in routes and handlers -- Record ALL roles/permissions that can access the feature (not just the primary ones) - -**Step 6: Specification Documentation** -- Apply Confidence Gating to each claim -- Accurately document specifications extracted from current implementation -- Only describe specifications clearly readable from code -- Reference the route list, data model, and test inventory from Steps 1-5 - -**Step 7: Minimal Confirmation Items** -- Only ask about truly undecidable important matters (maximum 3) -- Only parts related to business decisions, not implementation details +### Reverse PRD Investigation Boundary + +Use supplied scope and inventory as the coverage baseline; discover the feature boundary only when none is supplied. Account for every in-scope entry point at the PRD's user-behavior level. Trace implementation and tests far enough to establish observable outcomes, business rules, permissions, material error behavior and data constraints. Follow helpers, schemas or configuration when they can change one of those claims; routine internal details need no independent catalog. + +Group routes and interfaces that deliver the same requirement while preserving traceable coverage. Use existing tests as evidence, inspecting relevant assertions rather than transcribing every case. Document absent test evidence accurately. Record exact identifiers and enum values when they form a documented user/public contract; technical field inventories belong in Design Docs when needed. + +Continue across all feature behaviors and material boundaries after finding a problem. Stop investigation when the PRD claims and coverage are supported and remaining uncertainty cannot change them. Record inaccessible evidence and undecidable business intent explicitly. Ask the user only for a business decision that prevents faithful documentation; non-blocking unknowns remain documented. ### Quality Standards -- Verified content: 80%+ of core requirements -- Inferred content: 15% maximum with rationale -- Unverified content: Listed in "Undetermined Items" only -- Specification document with implementable specificity -- All routes from Step 1 are accounted for in the PRD -- All data model fields from Step 3 match the PRD's data model section + +- Core behavior claims have direct evidence; inferred intent is labeled with its basis. +- Every supplied entry point and inventory item is accounted for at the PRD abstraction level or excluded with a boundary reason. +- Permissions and independently failing observable boundaries remain represented. +- Detail supports product understanding and downstream design; internal call graphs and schema catalogs are included only when a product contract depends on them. +- Unknown business intent or metrics remain explicit instead of being fabricated to meet a percentage or template. diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 7b307aa5..6b23076e 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -193,7 +193,6 @@ Between tool calls, briefly report: which phase is running, the command executed ## Important Principles **Principles**: Follow these to maintain high-quality code: -- **Zero Error Principle**: Resolve all errors and warnings - **Correctness System Convention**: Follow strong correctness guarantees when applicable - **Test Fix Criteria**: Understand existing test intent and fix appropriately @@ -202,7 +201,6 @@ Between tool calls, briefly report: which phase is running, the command executed **Execution**: Apply fixes per coding-principles.md and testing-principles.md **Auto-fix**: Format, lint, unused imports (use project tools) **Manual fix**: Tests, contracts, logic (follow rule files) -**Continue until**: All checks pass OR blocked condition met **Required Fix Approaches** (fix at their source, not around them): - Test failures → Fix implementation or test logic to pass genuinely diff --git a/dev-workflows/agents/scope-discoverer.md b/dev-workflows/agents/scope-discoverer.md index 1b11cb04..1cf2222a 100644 --- a/dev-workflows/agents/scope-discoverer.md +++ b/dev-workflows/agents/scope-discoverer.md @@ -4,9 +4,6 @@ description: Discovers functional scope from existing codebase for reverse docum tools: Read, Grep, Glob, LS, Bash skills: - documentation-criteria - - ai-development-guide - - coding-principles - - implementation-approach - llm-friendly-context --- @@ -40,86 +37,25 @@ Document generation (PRD content, Design Doc content) is out of scope for this a Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units. -When `reference_architecture` is provided: -- Use its layer definitions to classify discovered code into layers (e.g., presentation/business/data for layered) -- Validate unit boundaries against RA expectations (units should align with layer boundaries) -- Note deviations from RA as findings in `uncertainAreas` +Use `reference_architecture` as a descriptive hint when it matches the code. Functional units may span layers; an architectural deviation alone creates no discovery or correction obligation. -### Execution Steps +### Discovery Boundary -1. **Entry Point Analysis** - - Identify routing files and map URL/endpoint to feature names - - Identify public API entry points - - If `existing_prd` is provided, read it and map PRD features to code areas +Establish coverage of the requested feature surface using repository entry points, module ownership, configuration and available tests. Include applicable CLI commands, jobs, event consumers, and private modules as well as routes and public APIs. Reuse supplied scope and existing PRDs as starting evidence. Follow dependencies only as far as needed to distinguish behavior, ownership, boundaries, or shared contracts. -2. **User Value Unit Identification** - - Group related endpoints/pages by user journey - - Identify self-contained feature sets - - Look for feature flags or configuration +Return a coherent functional unit for each independently meaningful capability. Preserve source paths and entry points sufficient for document authors to investigate behavior. Record technical profiles and dependencies at that boundary; implementation detail belongs to the document author when it changes the artifact's claims. -3. **Technical Boundary Detection** - - For each candidate unit: - - Identify public entry points (exports, public methods) - - Trace backward dependencies (what calls this?) - - Trace forward dependencies (what does this call?) - - Map module/service boundaries - - Identify interface contracts +For each unit, inventory applicable routes, test files and public exports from authoritative definitions and repository conventions. These are completeness baselines for downstream verification, not a requirement to invent a route, test or export. Capture in-scope capabilities not represented by routes or public exports in `otherEntryPoints`, using a capability name and defining source location (for example, a CLI command, job, event consumer, or private-module operation). Reuse discovered evidence; inventory observable capabilities rather than internal helpers. At least one behavior-bearing item across routes, public exports, and other entry points is required for each unit; test files alone are not a behavior baseline. -4. **Synthesis into Functional Units** - - Combine user-value groups and technical boundaries into functional units - - Each unit should represent a coherent feature with identifiable technical scope - - For each unit, identify its `valueProfile`: who uses it, what goal it serves, and what high-level capability it belongs to - - Apply Granularity Criteria (see below) +Complete coverage across relevant areas even after discovering one major feature. Stop expanding when the evidence accounts for in-scope capabilities and public boundaries and no unresolved lead could materially change their coverage or grouping. Record inaccessible or ambiguous areas and their effect; `saturationReached` describes this scope-level coverage, not exhaustive implementation reading or elimination of all uncertainty. -4.5. **Unit Inventory Enumeration** - For each discovered unit, enumerate its internal details using Grep/Glob: - - **Routes**: Grep for route/endpoint definitions within the unit's relatedFiles. Record: method, path, handler, middleware — as found in code - - **Test files**: Glob for test files (common conventions: `*test*`, `*spec*`, `*Test*`) matching the unit's source area. Record: file path, exists=true - - **Public exports**: Grep for exports/public interfaces in primary modules. Record: name, type (class/function/const), file path +### PRD Unit Grouping - Store results in `unitInventory` field per unit (see Output Format). This inventory provides completeness evidence. +Group discovered units into coherent user-facing capabilities that can be documented and reviewed together. Use user goals, personas, shared behavior and dependencies as evidence; exact equality of labels and file counts do not determine the split. Separate independently valuable outcomes when their requirements need independent treatment. Every discovered unit belongs to exactly one PRD unit's `sourceUnits`. -5. **Boundary Validation** - - Verify each unit delivers distinct user value - - Check for minimal overlap between units - - Identify shared dependencies and cross-cutting concerns +### Confidence -6. **Saturation Check** - - Expand the search only while another entry point, module, test, or interface can change discovered units, boundaries, relationships, inventories, or `uncertainAreas` - - Mark discovery as saturated when additional evidence inside `target_path`, `focus_area`, and any explicit governing boundary cannot change the output, and record what remains unexamined in `uncertainAreas` - -7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete) - - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units - - Grouping logic: units with the same `valueCategory` AND the same `userGoal` AND the same `targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units - - Every discovered unit must appear in exactly one PRD unit's `sourceUnits` - - Output as `prdUnits` alongside `discoveredUnits` (see Output Format) - -8. **Return JSON Result** - -## Granularity Criteria - -Each discovered unit should represent a Vertical Slice (see implementation-approach skill) — a coherent functional unit that spans all relevant layers — and satisfy: -1. Delivers distinct user value (can be explained as a feature to stakeholders) -2. Has identifiable technical boundaries (entry points, interfaces, related files) - -**Split signals** (unit may be too coarse): -- Multiple independent user journeys within one unit -- Multiple distinct data domains with no shared state - -**Cohesion signals** (units that may belong together): -- Units share >50% of related files -- One unit cannot function without the other -- Combined scope is still under 10 files - -Note: These signals are informational only during steps 1-6. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 7 after discovery is complete. - -## Confidence Assessment - -| Level | Triangulation Strength | Criteria | -|-------|----------------------|----------| -| high | strong | 3+ independent sources agree, clear boundaries | -| medium | moderate | 2 sources agree, boundaries mostly clear | -| low | weak | Single source only, significant ambiguity | +Base confidence on directness, authority and consistency of the evidence supporting each unit's behavior and boundary. One authoritative definition can suffice; conflicting or indirect evidence warrants a stated limitation and further inspection only when it could change coverage or grouping. ## Output Format @@ -143,8 +79,6 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "name": "Unit Name", "description": "Brief description", "confidence": "high|medium|low", - "triangulationStrength": "strong|moderate|weak", - "sourceCount": 3, "entryPoints": ["/path1", "/path2"], "relatedFiles": ["src/feature/*"], "dependencies": ["UNIT-002"], @@ -160,6 +94,7 @@ Note: These signals are informational only during steps 1-6. Keep all discovered "infrastructureDeps": ["database", "redis-cache"] }, "unitInventory": { + "otherEntryPoints": [], "routes": [ {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"} ], @@ -200,21 +135,16 @@ Note: These signals are informational only during steps 1-6. Keep all discovered } ``` +`otherEntryPoints` items have shape `{ "name": "capability", "file": "source/path:line" }`; use an empty array when routes and public exports already cover the unit. + ## Completion Criteria - [ ] Every discovered unit has an evidence-backed user-value boundary and technical boundary -- [ ] `unitInventory` accounts for the routes, test files, and public exports found inside the requested scope -- [ ] Granularity criteria were applied and each unit carries its value profile +- [ ] `unitInventory` accounts for the routes, test files, public exports, and other entry points found inside the requested scope +- [ ] Grouping reflects coherent capabilities and each unit carries its value profile - [ ] Relationships between units and any uncertain areas or limitations are recorded -- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` (step 7, after discovery completes) - -## Self-Validation [BLOCKING — before output] +- [ ] Every discovered unit appears in exactly one PRD unit's `sourceUnits` -Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. +## Evidence Check -- [ ] Output is limited to scope discovery (no PRD or Design Doc content generated) -- [ ] Every discovery cites its source evidence -- [ ] Low-confidence discoveries are reported with appropriate confidence markers -- [ ] Triangulation strength reflects actual source count (weak noted when single-source) -- [ ] Saturation check was performed before concluding discovery -- [ ] `saturationReached` is true only when additional evidence inside the semantic boundary cannot change the output +Return discovery results only. Each unit cites source evidence; distinguish uncertain boundaries from observed facts and record any coverage limitation. Set `saturationReached` according to the Discovery Boundary above. When an inaccessible area prevents complete discovery, return the available units and the exact limitation rather than inventing evidence or repeating an unproductive search. diff --git a/dev-workflows/agents/solver.md b/dev-workflows/agents/solver.md index 432d3676..fe52b5f3 100644 --- a/dev-workflows/agents/solver.md +++ b/dev-workflows/agents/solver.md @@ -59,7 +59,7 @@ This agent outputs **solution derivation and recommendation presentation**. Use - Failure points without impactAnalysis (e.g., discovered during verification): treat as direct fix candidates, note missing impact assessment in residualRisks ### Step 2: Solution Divergent Thinking -Generate every materially distinct feasible solution supported by the verified cause set. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: +Test removal or narrowing, then reuse, before retaining or adding a mechanism. Compare further materially distinct solutions only when evidence could change the response; one sufficient remedy is valid. Use the following perspectives only when they produce a genuinely different mechanism or scope decision: | Type | Definition | Application | |------|------------|-------------| @@ -74,7 +74,7 @@ Generate every materially distinct feasible solution supported by the verified c **Generated Solution Verification**: - Check if project rules have applicable guidelines -- For areas without guidelines, research current best practices via WebSearch to verify solutions align with standard approaches +- Consult authoritative external evidence only when an unresolved capability, compatibility or behavior fact could change the selected remedy - Map each solution to every confirmed failure point it resolves. Classify it as a complete remedy only when it addresses the complete supported cause set ### Step 3: Tradeoff Analysis @@ -95,7 +95,7 @@ Select from the materially distinct approaches only after the verified `closed` - Each step independently verifiable - Explicitly state dependencies between steps - Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior -- Include rollback procedures +- Include rollback or operational measures only when the proposed change affects a state or contract that requires them ## Output Format @@ -127,22 +127,24 @@ Select from the materially distinct approaches only after the verified `closed` "recommendation": { "selectedSolutionId": "S1", "rationale": "Detailed selection rationale", - "alternativeIfRejected": "Alternative solution ID if recommendation rejected", + "alternativeIfRejected": "Alternative solution ID when a sufficient alternative exists, otherwise null", "conditions": "Conditions under which this recommendation is appropriate" }, "implementationPlan": { "steps": [ - {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": "Rollback procedure if problems occur"} + {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": null} ], "criticalPoints": ["Points requiring special attention"] }, "uncertaintyHandling": { "residualRisks": ["Risks that may remain after resolution"], - "monitoringPlan": "Monitoring plan after resolution" + "monitoringPlan": null } } ``` +Populate `rollback` and `monitoringPlan` only when the selected remedy requires them; otherwise retain `null`. `alternativeIfRejected` is `null` when no decision-relevant sufficient alternative exists. + When verified cause coverage is not closed, return only: ```json @@ -158,7 +160,7 @@ When verified cause coverage is not closed, return only: The first criterion applies to both statuses. All later criteria and Self-Validation items apply only to `status: completed`. - [ ] Verified the input cause set is closed, or returned only `verification_required` with the exact next verification -- [ ] Generated every materially distinct feasible solution and counted only different mechanisms or scope decisions when the precondition passed +- [ ] Compared decision-relevant remedies, starting with subtraction and reuse, and selected a sufficient response to the complete verified cause set - [ ] Analyzed tradeoffs for each solution - [ ] Selected recommendation and explained rationale - [ ] Created concrete implementation steps diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 24abb82b..161d9263 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -66,7 +66,7 @@ Any YES is an implementation defect to correct. ### Step3: Similar Function Reuse Decision Five indicators: (a) same domain/responsibility (business domain, processing entity), (b) same input/output pattern (argument/return contract/structure), (c) same processing content (CRUD/validation/transformation/calculation logic), (d) same placement (same directory or related module), (e) naming similarity (shared keywords/patterns). -Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For every plausible candidate: +Use the indicators to find plausible candidates and apply the authoritative boundary below for escalation. For candidates that can materially change the selected implementation: 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; @@ -146,9 +146,7 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: -□ **Repository-wide verification**: confirm the pattern or dependency version is representative across the repository (not just the nearest 2-3 files) -□ **Dependency version verification** (external deps): verify repo-wide usage distribution; follow the version representative of the changed area and record that evidence when multiple versions coexist -□ **Coexistence resolution**: when multiple versions or patterns coexist, identify the majority for the changed area before choosing. When no established choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below +Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. #### Implementation Flow @@ -174,7 +172,7 @@ Return the final response per Structured Response Specification. For research/an ### Output Protocol - During execution, intermediate progress messages MAY be emitted as plain text or markdown. -- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion Response or Escalation Response). +- The LAST message returned to the orchestrator MUST be a single JSON object that matches one of the schemas below (Task Completion, Blocked, or Escalation Response). - Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`. ### Field Specifications @@ -183,11 +181,11 @@ Return the final response per Structured Response Specification. For research/an **newTestsPassed**: Set to `true` only for an observed passing test run. Use `false` with the exact result in `runnableCheck` when tests fail or the environment prevents execution. -**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` when the command succeeds without error. +**runnableCheck.result**: For test evidence, use `passed` only when at least one executed assertion ran against the behavior the task is supposed to deliver; record skipped tests, placeholder/TODO-only bodies, assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`), or test-runner reports of 0 tests matched as `skipped`. Tests that verify intentional absence (e.g., `expect(queryAllBy*).toHaveLength(0)`) are substantive when the absence is the task's expectation. For non-test verification (build, typecheck, CLI execution, artifact checks), use `passed` only when the observed result establishes the supplied or derived verification condition. A successful exit proves command execution, not an unobserved behavior or artifact postcondition. **mutationEvidence**: Use `[]` when no mutation verification ran; otherwise populate every field in the schema below with revision-bound evidence. -**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include every candidate evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -206,7 +204,11 @@ Complete this agent's work by returning the following JSON; the quality assuranc } ``` -### 2. Escalation Response +### 2. Blocked Response + +When required implementation remains incomplete and available in-scope recovery supplies no advancing action, return `{"status":"blocked","taskName":"task","changeSummary":"completed work","remainingWork":["required unfinished result"],"evidence":["attempt and observed blocker"],"runnableCheck":{"result":"failed|skipped","reason":"exact affected proof"}}`. Preserve unfinished checkboxes. Verification unavailable after completed implementation remains a `completed` implementation result with an exact skipped/failed check for downstream quality assurance. + +### 3. Escalation Response Use this response when evidence establishes either authoritative escalation condition. @@ -224,12 +226,12 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. -☐ All implementation items completed with evidence, or the response proves one authoritative escalation condition +☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep -☐ `reuseDecisions` records every plausible similar implementation and its evidence-backed reuse, extend, or separate disposition +☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification -☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification +☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification **ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 63ace229..4fc6ccba 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -21,7 +21,9 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Inputs +- **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode +- **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` - **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists - **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc @@ -119,7 +121,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Output - ADR batch: contiguous `docs/adr/ADR-[4-digit number]-[title].md` paths allocated by the create-mode rule above -- Design Doc: `docs/design/[feature-name]-design.md` +- Design Doc: supplied `output_path`, otherwise `docs/design/[feature-name]-design.md`. Confirm a create destination is absent or belongs to the same intended artifact before writing; a different existing artifact requires a distinct path. - Follow the applicable template; remove only non-applicable optional content. - ADR batch result: `{"status":"completed","documentType":"ADRBatch","paths":["path"]}` - Design Doc result: `{"status":"completed","documentType":"DesignDoc","path":"path"}` diff --git a/dev-workflows/agents/verifier.md b/dev-workflows/agents/verifier.md index c483651d..ccccf51b 100644 --- a/dev-workflows/agents/verifier.md +++ b/dev-workflows/agents/verifier.md @@ -43,19 +43,13 @@ Solution derivation is out of scope for this agent. **impactAnalysis Validity Check**: - Verify the logical validity of each failure point's impactAnalysis using only the supplied investigation evidence; perform additional searches in Step 2 -### Step 2: Triangulation Supplementation -Identify source types NOT covered in the investigation's `investigationSources`, then investigate at least one: +### Step 2: Independent Evidence Check -1. Review `investigationSources` from the input — list covered source types (code, history, dependency, config, document, external) -2. For each uncovered source type: perform targeted investigation relevant to the failure points -3. If all source types were covered: investigate a **different code area** or **different configuration** not mentioned in the original investigation +Independently check the decisive claims, counter-evidence and scope closure against their authoritative sources. Expand to another source or area only when it can change a failure-point judgment or close a material coverage gap. An already decisive source needs no unrelated corroboration. Record the evidence and its effect. -Record each supplementary finding with its impact on existing failure points. +### Step 3: External Evidence (Conditional) -### Step 3: External Information Reinforcement (WebSearch) -- Official information about failure points found in investigation -- Similar problem reports and resolution cases -- Technical documentation not referenced in investigation +Consult authoritative external sources when an unresolved technology behavior, dependency capability or version fact can change the diagnosis and repository evidence cannot decide it. ### Step 4: Investigation Coverage Check Check the upstream investigation's pathMap for completeness: @@ -123,12 +117,8 @@ Set `coverageDisposition` independently: "pathMapCoverage": "Assessment of path coverage completeness", "identifiedGaps": ["Missing paths or unchecked nodes"] }, - "triangulationSupplements": [ - {"source": "Additional information source investigated", "findings": "Content discovered", "impactOnFailurePoints": "Impact on existing failure points"} - ], - "externalResearch": [ - {"query": "Search query used", "source": "Information source", "findings": "Related information discovered", "impactOnFailurePoints": "Impact on failure points"} - ], + "triangulationSupplements": [], + "externalResearch": [], "coverageCheck": { "scopeEnvelopeAccounting": [ {"scopeItem": "Scope-envelope item", "status": "closed|material_gap|evidence_unavailable", "evidence": "Coverage evidence", "nextInvestigationTarget": "Exact target or null"} @@ -166,8 +156,8 @@ Set `coverageDisposition` independently: ## Completion Criteria -- [ ] Performed Triangulation supplementation and collected additional information -- [ ] Collected external information via WebSearch +- [ ] Independently verified decisive evidence and closed material coverage gaps +- [ ] Used external evidence when unresolved technology facts could change the diagnosis - [ ] Checked pathMap coverage (missing paths, unchecked nodes) - [ ] Performed Devil's Advocate evaluation on each failure point - [ ] Weakened finalStatus for failure points with official documentation-based counter-evidence diff --git a/dev-workflows/skills/ai-development-guide/SKILL.md b/dev-workflows/skills/ai-development-guide/SKILL.md index fd97e36d..b3c9e991 100644 --- a/dev-workflows/skills/ai-development-guide/SKILL.md +++ b/dev-workflows/skills/ai-development-guide/SKILL.md @@ -68,7 +68,7 @@ Make all errors visible and traceable with full context. Prioritize primary code - The same failure is caught at multiple layers without a single recovery owner - Nested handlers obscure which state is committed, rolled back, or exposed - A handler converts a failure to success/default output without an observable degraded-state contract -- Error handlers that return default values without logging +- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal. @@ -143,7 +143,7 @@ Keep concrete implementations separate while their apparent similarity is accide - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis +- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness diff --git a/dev-workflows/skills/coding-principles/SKILL.md b/dev-workflows/skills/coding-principles/SKILL.md index af2be9c8..bd3ede0b 100644 --- a/dev-workflows/skills/coding-principles/SKILL.md +++ b/dev-workflows/skills/coding-principles/SKILL.md @@ -70,15 +70,9 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -### Verifying References Before Adoption -When adopting patterns, APIs, or dependencies from existing code: -- **IF** a reference sample covers only nearby files → **THEN** confirm the pattern is representative by checking relevant repository usage before adopting -- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient -- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it -- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update) - -### Principle -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model. +Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations diff --git a/dev-workflows/skills/documentation-criteria/references/prd-template.md b/dev-workflows/skills/documentation-criteria/references/prd-template.md index d1892ee8..8d814d76 100644 --- a/dev-workflows/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows/skills/documentation-criteria/references/prd-template.md @@ -94,6 +94,8 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r ## Success Criteria +State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. + ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] 2. [Metric name]: [numeric target] measured by [method] within [timeframe] @@ -134,7 +136,7 @@ Include only evidenced product or delivery risks that can change scope, success - [ ] [Question 1]: [Description of options or impacts] - [ ] [Question 2]: [Description of options or impacts] -*Discuss with user until this section is empty, then delete after confirmation* +Resolve only questions that block the current document or next decision. Retain non-blocking unknowns with their effect; in as-is documentation, unknown business intent is not a reason to invent requirements. ## Appendix diff --git a/dev-workflows/skills/external-resource-context/SKILL.md b/dev-workflows/skills/external-resource-context/SKILL.md index 344caaea..1c4da6e7 100644 --- a/dev-workflows/skills/external-resource-context/SKILL.md +++ b/dev-workflows/skills/external-resource-context/SKILL.md @@ -36,17 +36,17 @@ When the file is absent or the resource is unreachable, continue from governing ## Capturing and Updating Records -Capturing a record requires an interactive hearing. The workflow using this skill owns the interaction mechanism and routing. Follow [references/hearing.md](references/hearing.md) for the hearing conditions, domain routing, two-phase hearing, storage protocol, and quality checklist. +Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow [references/hearing.md](references/hearing.md) for evidence, questions and storage. ## Output Format -The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. +Use [references/template.md](references/template.md) for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence. For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). ## References -- [references/hearing.md](references/hearing.md) — Hearing conditions, domain routing, storage protocol, quality checklist +- [references/hearing.md](references/hearing.md) — Decision-specific capture and storage - [references/frontend.md](references/frontend.md) — Frontend domain axes - [references/backend.md](references/backend.md) — Backend domain axes - [references/api.md](references/api.md) — API contract domain axes diff --git a/dev-workflows/skills/external-resource-context/references/api.md b/dev-workflows/skills/external-resource-context/references/api.md index b9a3510e..42d2a3db 100644 --- a/dev-workflows/skills/external-resource-context/references/api.md +++ b/dev-workflows/skills/external-resource-context/references/api.md @@ -1,60 +1,10 @@ -# API Contract Domain Axes +# Api Resource Cues -Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: API Schema Source +- **Schema**: OpenAPI, Protobuf, GraphQL or code-first definition for the affected API. +- **Mock environment**: Existing entry point and whether it preserves the claimed contract. +- **Authentication**: Mechanism and credential-source reference needed for authorized verification. +- **Schema change process**: Versioning or compatibility rule governing the changed contract. -The canonical source of API contracts (request/response shapes, endpoints, RPC methods). - -**Question choices**: -- OpenAPI / Swagger specification (file in repository or hosted URL) -- Protobuf definitions (file in repository) -- GraphQL schema (SDL file or introspection endpoint) -- TypeScript or other code-first contract definitions in the repository -- No formal contract (ad-hoc JSON) -- Not applicable - -**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. - -## Axis 2: Mock Environment - -How clients exercise the API without depending on the live server. - -**Question choices**: -- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) -- Hand-written mock server in the repository -- Hosted mock service (URL) -- Live development server (no separate mock) -- Not applicable - -**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. - -## Axis 3: Authentication Method - -How the API authenticates and authorizes requests. - -**Question choices**: -- Bearer token (e.g., JWT) issued by an auth service -- API key in a header or query parameter -- Session cookie set by a separate login flow -- Mutual TLS -- No authentication -- Not applicable - -**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. - -## Axis 4: Schema Change Process (When Relevant) - -How breaking and non-breaking schema changes are reviewed and rolled out. - -**Question choices**: -- Documented contract review process (link to the document) -- Versioned endpoints (e.g., `/v1/`, `/v2/`) -- Backward-compatible changes only, no formal versioning -- Not applicable - -**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows/skills/external-resource-context/references/backend.md b/dev-workflows/skills/external-resource-context/references/backend.md index ffc27403..2d9c0535 100644 --- a/dev-workflows/skills/external-resource-context/references/backend.md +++ b/dev-workflows/skills/external-resource-context/references/backend.md @@ -1,60 +1,10 @@ -# Backend Domain Axes +# Backend Resource Cues -Hearing axes for tasks that involve server-side, data, or storage work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Database Schema Source +- **Database schema**: Authoritative migration, schema file or registry for the affected contract. +- **Migration history**: Relevant tool and history when state conversion affects the decision. +- **Secret store**: Location and retrieval mechanism only; keep secret values out of records. +- **Background jobs**: Queue or scheduler and inspection method when delivery behavior matters. -The canonical source of the database schema (tables, columns, indexes, constraints). - -**Question choices**: -- Migration files in the repository (e.g., a `migrations/` directory) -- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) -- Database MCP that introspects a live database -- External schema registry (URL or hosted catalog) -- No persistent database -- Not applicable - -**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. - -## Axis 2: Migration History - -How schema changes are tracked over time. - -**Question choices**: -- Versioned migration files in the repository -- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) -- Manual change log document -- No migration tracking -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. - -## Axis 3: Secret Store - -Where credentials, API keys, and other secrets are stored and accessed. - -**Question choices**: -- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) -- Environment variables loaded from a `.env` file (development only) -- Encrypted file in the repository -- No secrets required -- Not applicable - -**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. - -## Axis 4: Background Job Infrastructure (When Relevant) - -How asynchronous work is dispatched and observed. - -**Question choices**: -- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) -- Cron / scheduled tasks managed by deployment platform -- In-process worker thread -- No background work -- Not applicable - -**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows/skills/external-resource-context/references/frontend.md b/dev-workflows/skills/external-resource-context/references/frontend.md index b90b4e29..76ae7d6e 100644 --- a/dev-workflows/skills/external-resource-context/references/frontend.md +++ b/dev-workflows/skills/external-resource-context/references/frontend.md @@ -1,60 +1,10 @@ -# Frontend Domain Axes +# Frontend Resource Cues -Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Design Origin +- **Design origin**: Canonical visual source or specification and the applicable node/version. +- **Design system**: Component/token documentation or package that determines this UI contract. +- **Guidelines**: A sourced usage or accessibility requirement that constrains this change. +- **Visual verification**: Existing rendering entry point, harness or access method needed to observe the UI. -The canonical source of the visual specification. - -**Question choices**: -- Design tool (e.g., a hosted design platform) -- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) -- Public documentation URL -- Existing implementation only (no separate design source) -- Not applicable - -**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. - -## Axis 2: Design System - -Reusable component library and design tokens. - -**Question choices**: -- Component library with MCP server access -- Component library with documentation URL -- Storybook or equivalent component catalog -- Internal package without external documentation -- No design system (ad-hoc components) -- Not applicable - -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. - -## Axis 3: Guidelines - -Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. - -**Question choices**: -- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) -- External documentation site -- Inline guidance in the design system catalog -- No documented guidelines -- Not applicable - -**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. - -## Axis 4: Visual Verification Environment - -How rendered output is confirmed during implementation. - -**Question choices**: -- End-to-end test runner with screenshot capability -- Storybook or equivalent isolated component preview -- Browser automation tool (dedicated CLI or MCP server) -- Manual browser inspection only -- Not applicable - -**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows/skills/external-resource-context/references/hearing.md b/dev-workflows/skills/external-resource-context/references/hearing.md index e81156f3..971c0bc2 100644 --- a/dev-workflows/skills/external-resource-context/references/hearing.md +++ b/dev-workflows/skills/external-resource-context/references/hearing.md @@ -1,52 +1,18 @@ -# External Resource Hearing and Storage +# External Resource Capture -Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism. +Capture a resource only when repository and supplied evidence cannot decide a current design, implementation or verification question without it. Absence of a project record does not trigger a domain-wide questionnaire. -## When to Hear +## Resolve Access -| Condition | Action | -|-----------|--------| -| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | -| File exists and covers the current decision | Use it without an update question | -| The governing request identifies changed environment facts | Run diff-only hearing for the named axes | -| A relevant axis is absent | Hear only the missing axis | -| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation | +1. Name the decision and required external fact. Read the existing project entry and feature identifier when available. +2. Reuse access details from the user, governing artifacts or repository configuration. Fetch the selected content within current authority. A new record can be written from this evidence without a hearing. +3. Ask only for a missing location, access method or user-owned interpretation that prevents the decision. The calling workflow owns interaction; an autonomous consumer returns the exact missing evidence to that caller and continues independent work. +4. Correct stale details when authoritative current evidence establishes the replacement. When it does not, preserve the last known record, report the failed access and ask only for the unresolved decision-relevant fact. Record locations and access mechanisms, never secret values. -## Domain Routing +## Optional Domain Cues -Load the domain reference matching the current task: +Load only the reference needed to locate the selected fact: [frontend.md](frontend.md), [backend.md](backend.md), [api.md](api.md), or [infra.md](infra.md). Their lists are cues, not required questions or completion axes. -| Task type | References to load | -|-----------|--------------------| -| Frontend (UI work) | [frontend.md](frontend.md) | -| Backend (server / data work) | [backend.md](backend.md) | -| API contract work | [api.md](api.md) | -| Infrastructure / deployment | [infra.md](infra.md) | -| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure | +## Store -Each domain reference defines the axes and the question template. - -## Two-Phase Hearing - -1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). - -2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration. - -For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis. - -## Storage Protocol - -After hearing completes: - -1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure. -2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. -3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). -4. Report the file paths back to the calling workflow. - -## Quality Checklist - -- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" -- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes -- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command) -- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier -- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision +Use [template.md](template.md) for `docs/project-context/external-resources.md`. Keep environment facts at project level and feature-specific identifiers in the consuming document's `External Resources Used` table. Preserve unrelated entries and stable labels. Create no empty record or N/A catalog when no external source is required. Return changed paths and any exact remaining evidence limitation to the caller. diff --git a/dev-workflows/skills/external-resource-context/references/infra.md b/dev-workflows/skills/external-resource-context/references/infra.md index 932a416d..0529df4d 100644 --- a/dev-workflows/skills/external-resource-context/references/infra.md +++ b/dev-workflows/skills/external-resource-context/references/infra.md @@ -1,60 +1,10 @@ -# Infrastructure Domain Axes +# Infra Resource Cues -Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: IaC Source +- **IaC source**: Relevant checked-in or external infrastructure definition. +- **Environment configuration**: Configuration source for the specific environment and question. +- **Secrets**: Secret-store reference and access mechanism, never values. +- **Deployment trigger**: Existing execution/approval boundary only when it affects current implementation or verification. -The canonical source of infrastructure definitions. - -**Question choices**: -- Terraform configuration in the repository -- Pulumi or CDK code in the repository -- Kubernetes manifests / Helm charts in the repository -- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) -- Manual console configuration (no IaC) -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. - -## Axis 2: Environment Configuration - -How per-environment settings (development, staging, production) differ. - -**Question choices**: -- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) -- Environment variables managed by the deployment platform -- Workspace or stack abstraction in the IaC tool itself -- Single shared configuration (no per-environment differences) -- Not applicable - -**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. - -## Axis 3: Secrets in Infrastructure - -How infrastructure code references secrets without exposing them. - -**Question choices**: -- Secrets sourced from a secret manager via IaC data lookup -- Secrets injected at apply time via environment variables -- Encrypted secret files committed alongside IaC -- No secrets in infrastructure -- Not applicable - -**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. - -## Axis 4: Deployment Trigger - -How infrastructure and application changes reach environments. - -**Question choices**: -- CI pipeline triggered on merge to a specific branch -- Manual approval step in CI -- Local apply by an operator -- Deployment platform's auto-deploy on push -- Not applicable - -**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/dev-workflows/skills/external-resource-context/references/template.md b/dev-workflows/skills/external-resource-context/references/template.md index 169f3b29..8321a7ac 100644 --- a/dev-workflows/skills/external-resource-context/references/template.md +++ b/dev-workflows/skills/external-resource-context/references/template.md @@ -1,115 +1,31 @@ # Storage Templates -Two templates: the project-tier file and the feature-tier section. +## Project Record -## Project-Tier Template - -Path: `docs/project-context/external-resources.md` +Path: `docs/project-context/external-resources.md`. Preserve existing resource labels referenced by feature documents. Include only resources actually needed; adapt grouping to the existing file. ```markdown # External Resources -Last updated: YYYY-MM-DD - -This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. - -## Frontend - -### Design Origin -- Status: -- Source type: -- Location: -- Access method: - -### Design System -- Status: -- Source type: -- Location: -- Access method: - -### Guidelines -- Status: -- Source type: -- Location: -- Access method: - -### Visual Verification Environment -- Status: -- Tool type: -- Entry: - -## Backend - -### Database Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Migration History -- Status: -- Tool: -- Location: -- Apply trigger: - -### Secret Store -- Status: -- Service: -- Access method: - -### Background Job Infrastructure -- Status: -- Service: -- Access method: - -## API - -### API Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Mock Environment -- Status: -- Source type: -- Entry: - -### Authentication Method -- Status: -- Mechanism: -- Credential source: - -### Schema Change Process -- Status: -- Process: - -## Infrastructure - -### IaC Source -- Status: -- Tool: -- Location: -- Apply trigger: - -### Environment Configuration -- Status: -- Mechanism: -- Environments: +## [Stable resource label] +- Purpose: [decision or contract served] +- Location: [URL, path, package or service] +- Access method: [read operation, tool or command within existing authority] +- Evidence: [source and relevant version/date] +``` -### Secrets in Infrastructure -- Status: -- Mechanism: +Keep credentials and secret values outside this record. Record an access limitation when it affects a consumer; a failed fetch does not establish that the resource is absent. -### Deployment Trigger -- Status: -- Mechanism: +## Feature Reference -## Additional Resources +Use the consuming document's natural heading level for `External Resources Used`. -Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. +```markdown +## External Resources Used -- : — — +| Project resource label | Feature-specific identifier | Use | +|---|---|---| +| [existing label] | [node, endpoint, module or version selector] | [decision or proof] | ``` -Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). +Project entries own shared locations and access methods; feature rows own only the subset and identifiers used here. diff --git a/dev-workflows/skills/integration-e2e-testing/SKILL.md b/dev-workflows/skills/integration-e2e-testing/SKILL.md index 53987b3b..aa037f1f 100644 --- a/dev-workflows/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows/skills/integration-e2e-testing/SKILL.md @@ -1,121 +1,17 @@ --- name: integration-e2e-testing -description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when designing integration tests, E2E tests, or reviewing test quality. +description: Defines integration/E2E skeleton annotations, lane and file contracts, and route-parity review criteria. Use when generating or consuming test skeletons or reviewing shared mutation routes. --- -# Integration and E2E Testing Principles +# Integration and E2E Skeleton Contracts -## References +## Test Lanes -**E2E test design**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection. - -## Test Type Definition and Standard Budgets - -| Test Type | Purpose | Scope | External Deps | Standard Budget per Input Design Doc | Implementation Timing | -|-----------|---------|-------|---------------|-------------------|----------------------| -| Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | -| fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | - -**Lane selection (E2E only)**: -- Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup -- Add **service-integration-e2e** only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely - -One input Design Doc is one budget scope: apply each lane budget once across all ACs and candidates in that document. The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa. Treat the numbers above as enforced standard budgets. Exceed a budget only when an accepted requirement or a distinct failure mode cannot be proved by a selected test; annotate that exception and why consolidation cannot cover it. - -## Behavior-First Principle - -### Include (High ROI) -- Business state transitions observable across components -- Data integrity and persistence behavior -- User-visible functionality completeness -- Error handling behavior (what user sees/experiences) - -### Redirect to Other Test Types -- Calculation and data transformation rules → Verify via unit tests of the logic that owns them -- External service connections → Verify via contract/interface tests -- Performance metrics → Verify via dedicated load testing -- Implementation details → Verify observable behavior instead -- UI layout specifics → Verify information availability instead - -**Principle**: Test = User-observable behavior verifiable in isolated CI environment - -## ROI Calculation - -ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently. - -For every candidate, record the governing evidence for each ROI input before assigning a value. Use an approved PRD, confirmed requirement context, accepted contract or legal obligation, user-confirmed test value context, Design Doc boundary, and existing-test evidence as applicable. A missing value is `unknown`, not `0`, and an inference is not observed evidence. - -When ROI can change candidate ranking, a lane threshold, or budget selection, return the exact missing product input and its decision effect when `test_value_context` has not yet supplied it. After that single input round, apply the supplied facts and retain every remaining value as decision-relevant `unknown` with its numeric score unset. Resolve Defect Detection from repository evidence at the proof boundary and in existing tests. When selection is invariant because the candidate is removed before ROI, is the sole eligible candidate for a reserved journey slot, or all surviving candidates fit an unthresholded budget, record the unknown as `not_decision_relevant` and keep its numeric score unset. - -### Unknown-Value Ordering - -For candidates with a decision-relevant `unknown` after the value-input round, use accepted legal or contractual obligation, explicit connection to the confirmed user or business outcome, distinct Defect Detection evidence, lower lane ownership cost, then source AC order. Select the smallest set that proves the accepted obligations and confirmed outcome boundaries, within the normal lane budgets. Numeric lane thresholds apply to fully scored candidates; this evidence ordering supplies the selection decision for affected candidates. Record the unknown input, evidence checked, and selection effect. - -For resolved numeric inputs, use exactly `0`, `5`, or `10`. Legal Requirement remains boolean; a governing-source check that finds no accepted legal, regulatory, contractual, or audit obligation supports `false` and records that checked source. - -| Input | Scale | -|---|---| -| Business Value | 0 = no user/business outcome; 5 = meaningful but non-critical outcome; 10 = core, revenue, safety, or data-integrity outcome | -| User Frequency | 0 = unreachable/obsolete; 5 = regular subset of users or runs; 10 = dominant journey or execution path | -| Legal Requirement | `true` only when an accepted legal, regulatory, contractual, or audit requirement applies; otherwise `false` | -| Defect Detection | 0 = duplicates existing proof; 5 = covers a distinct branch/state; 10 = uniquely detects a critical boundary or cross-service failure | - -``` -ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection - (range: 0–120) -``` - -Higher ROI Score = higher priority within its test type. For equal scores, order by Legal Requirement (`true` first), then higher Defect Detection, Business Value, User Frequency, and finally source AC order. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores. - -### ROI Thresholds by Lane - -The two E2E lanes have different ownership costs and use independent standard thresholds. - -| Lane | ROI threshold | Rationale | -|------|---------------|-----------| -| fixture-e2e | ROI ≥ 20 (beyond reserved slot) | Cost is comparable to integration tests once the harness exists; the floor avoids filling MAX 3 with low-signal tests when fewer would suffice | -| service-integration-e2e | ROI > 50 (beyond reserved slot) | Live-service setup, state cleanup, and failure diagnosis add material ownership cost; reserve for journeys whose value cannot be proven any other way | - -Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Emit a below-floor candidate beyond the reserved slot only when an accepted requirement or a distinct uncovered failure mode justifies the exception. Leave budget intentionally unfilled rather than padding with low-value tests; record any threshold or budget exception in the skeleton that carries the exception. - -### ROI Calculation Examples - -| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome | -|----------|----|------|-------|--------|-----------|-----------|-------------------| -| Core checkout UI flow | 10 | 10 | true | 10 | 120 | fixture-e2e | Selected (reserved slot: user-facing multi-step journey, browser-level verification with fixtures) | -| Core checkout against live payment service | 10 | 10 | true | 10 | 120 | service-integration-e2e | Selected (real-service correctness above ROI threshold) | -| Dismiss button updates UI state | 5 | 10 | false | 5 | 55 | fixture-e2e | Selected (rank 2 of 3 fixture-e2e budget) | -| Payment error message display | 5 | 5 | false | 5 | 30 | fixture-e2e | Selected (rank 3 of 3 fixture-e2e budget) | -| Optional filter toggle | 5 | 5 | false | 0 | 25 | fixture-e2e | Removed during deduplication (duplicates existing proof) | -| Payment retry against real provider | 5 | 5 | false | 5 | 30 | service-integration-e2e | Below ROI threshold (30 < 50), not selected | -| DB persistence check | 10 | 5 | false | 10 | 60 | Integration | Selected (rank 1 of 3) | -| Pure data transformation | 5 | 5 | false | 5 | 30 | Unit | Not selected (push down to unit test) | - -## Multi-Step User Journey Definition - -A candidate qualifies as a **multi-step user journey** when ALL of the following are true: - -1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type: - - Web: distinct routes/pages - - Mobile native: distinct screens/views - - CLI: distinct command invocations or interactive prompts - - API: distinct API calls forming a transaction (e.g., create → confirm → finalize) -2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays -3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow) - -### User-Facing vs Service-Internal Journeys - -Multi-step journeys are classified for reserved-slot eligibility: - -| Classification | Condition | Reserved Slot Eligibility | Example | -|---|---|---|---| -| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible — defaults to **fixture-e2e** reserved slot. Add a service-integration-e2e reserved slot only when the journey's correctness depends on real cross-service behavior | Web checkout flow, CLI setup wizard, mobile onboarding | -| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot — use integration tests. Service-integration-e2e through normal ROI > 50 path is still valid when full-system verification is warranted | Async job pipeline, service-to-service saga, scheduled batch processing | - -This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above. - -Use this definition when evaluating E2E test candidates and E2E gap detection. +| Lane | Observable boundary | Dependencies | +|------|---------------------|--------------| +| `integration` | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary | +| `fixture-e2e` | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary | +| `service-integration-e2e` | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary | ## Test Skeleton Specification @@ -126,18 +22,11 @@ Each test MUST include the following annotations: ``` AC: [Original acceptance criteria text] Behavior: [Trigger] → [Process] → [Observable Result] -@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e @lane: integration | fixture-e2e | service-integration-e2e @dependency: none | [component names] | full-system -@complexity: low | medium | high -ROI: [score] +Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient] ``` -**`@lane` selection rule**: -- `integration` — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language) -- `fixture-e2e` — Browser-level UI verification with mocked backend / fixture-driven state -- `service-integration-e2e` — Browser-level or end-to-end verification against running local services or stubs - Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). ### Verification Items (Optional) @@ -149,33 +38,14 @@ Verification items: - [Item 2] ``` -## EARS Format Mapping - -| EARS Keyword | Test Type | Generation Approach | -|--------------|-----------|---------------------| -| **When** | Event-driven | Trigger event → verify outcome | -| **While** | State condition | Setup state → verify behavior | -| **If-then** | Branch coverage | Both condition paths verified | -| (none) | Basic functionality | Direct invocation → verify result | - ## Test File Naming Convention - Integration tests: `*.int.test.*` or `*.integration.test.*` - fixture-e2e tests: `*.fixture.e2e.test.*` (or organize under `tests/e2e/fixture/`) - service-integration-e2e tests: `*.service.e2e.test.*` (or organize under `tests/e2e/service/`) -The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing and budget accounting. - -## Review Criteria - -### Skeleton and Implementation Consistency - -| Check | Failure Condition | -|-------|-------------------| -| Behavior Verification | No assertion for "observable result" in the implemented test | -| Verification Item Coverage | Listed items not all covered by assertions | -| Mock Boundary | Internal components mocked in integration test | +The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing. -### Route Parity for Shared Mutations +## Route Parity for Shared Mutations -When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure. diff --git a/dev-workflows/skills/integration-e2e-testing/references/e2e-design.md b/dev-workflows/skills/integration-e2e-testing/references/e2e-design.md deleted file mode 100644 index 7c1e95a0..00000000 --- a/dev-workflows/skills/integration-e2e-testing/references/e2e-design.md +++ /dev/null @@ -1,72 +0,0 @@ -# E2E Test Design (Browser Harness) - -This reference uses Playwright as the default browser harness. Adapt patterns to the project's chosen framework when different (Cypress, Selenium, etc.); the lane definitions, ROI rules, and budgets remain the same. - -## Two E2E Lanes - -E2E tests in this workflow split into two lanes (see parent skill Test Type Definition): - -| Lane | When | ROI gate | Cost | -|------|------|----------|------| -| **fixture-e2e** | UI journey verification with deterministic fixtures (mocked backend / fixture data) | ROI ≥ 20 (beyond reserved slot); selected by ranking within MAX 3 budget | Comparable to integration; runs in CI without infrastructure setup | -| **service-integration-e2e** | Journey correctness depends on real cross-service behavior (data persistence, transactional consistency, external contracts) | ROI > 50 (beyond reserved slot) | Higher setup, state-cleanup, and diagnosis cost; reserved for what cannot be faked safely | - -The **reserved slot** referenced in the ROI gates is a per-lane slot for a qualifying multi-step user journey that is emitted regardless of its ROI score; it is defined in the parent skill's *Multi-Step User Journey Definition* section. - -## When to Create E2E Tests - -E2E candidates target **critical user journeys** that span multiple pages or require real browser interaction. Pick the lane based on whether real services are required for the verification. - -### Candidate Sources - -| Source | What to Extract | -|--------|----------------| -| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens | -| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) | -| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification | -| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) | - -### Selection Criteria - -**Include** (high E2E ROI): -- Multi-page user journeys (login → dashboard → action → confirmation) -- Flows requiring real browser APIs (navigation, cookies, localStorage) -- Accessibility verification requiring actual DOM rendering -- Responsive behavior across viewports - -**Use integration tests instead when**: -- Testing single-component state changes → in-process component renderer (e.g., RTL for React/TS) -- Testing API response handling → in-process API mock + component renderer (e.g., MSW + RTL for React/TS) -- Testing pure data transformations → unit tests - -## UI Spec to E2E Test Mapping - -When a UI Spec exists, use it as the primary source for E2E test design: - -1. **Extract screen transitions** → Each multi-step transition = 1 E2E candidate -2. **Check state x display matrix** → Error states requiring navigation = E2E candidate -3. **Review interaction definitions** → Browser-dependent interactions = E2E candidate -4. **Cross-reference with Design Doc ACs** → Ensure E2E candidates map to acceptance criteria - -### Mapping Template - -``` -Screen Transition: [Screen A] → [Screen B] → [Screen C] -AC Reference: AC-{id} -User Journey: [Description of what the user accomplishes] -Lane: fixture-e2e | service-integration-e2e -Preconditions: [Auth state, data state — note whether these are fixture-driven or live] -Verification Points: - - [What to assert at each step] -E2E ROI Score: [calculated score] -``` - -**Lane decision**: choose `fixture-e2e` by default. Promote to `service-integration-e2e` when the verification requires observing real cross-service behavior (e.g., the test asserts that data persists across a real DB write, or that an external service receives the correct payload). - -## Budget Enforcement - -Standard budgets per input Design Doc (same as parent skill): -- **fixture-e2e**: MAX 3 tests, ROI ≥ 20 beyond the reserved slot (selected by ranking) -- **service-integration-e2e**: MAX 1-2 tests, ROI > 50 beyond the reserved slot -- Prefer fewer, comprehensive journey tests over many granular tests in both lanes -- Exceed a standard budget only for an accepted requirement or distinct uncovered failure mode, and record why the selected tests cannot be consolidated diff --git a/dev-workflows/skills/llm-friendly-context/SKILL.md b/dev-workflows/skills/llm-friendly-context/SKILL.md index 73cc23e6..6ff8fcf1 100644 --- a/dev-workflows/skills/llm-friendly-context/SKILL.md +++ b/dev-workflows/skills/llm-friendly-context/SKILL.md @@ -16,7 +16,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Example: "Preserve existing public API behavior across the documented compatibility cases." 2. **Make vague instructions concrete** - - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions. - Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. 3. **Specify output shape** @@ -30,7 +30,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Follow references while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task. - Each step needs a checkpoint: what evidence proves it is complete. 6. **Permit uncertainty explicitly** @@ -40,7 +40,7 @@ The goal is stable downstream execution: the next consumer should know what to r 7. **Keep constraints proportionate** - Add only constraints that reduce ambiguity or preserve a real requirement. - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. - - Apply `minimal`, `a few lines`, and explicit line estimates to the completed diff as one total budget. + - Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count. ## Rewrite Patterns @@ -49,7 +49,7 @@ Use these rewrites before treating a prompt, handoff, or artifact as complete. | Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | -| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule | +| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | @@ -68,7 +68,7 @@ Before sending a prompt or artifact to another consumer, verify: - [ ] Accepted decisions and constraints use one canonical wording. - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. -- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains. - [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative. - [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner. diff --git a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md index 2a4f473e..479d208a 100644 --- a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md @@ -43,14 +43,7 @@ Document paths: $ARGUMENTS ### Step 1: Discover and Validate Documents -Confirm `$ARGUMENTS` names at least one existing document path; report and end when it is empty or every path is unresolvable. Then discover the remaining Design Docs, UI Specs, and PRDs under `docs/design/`, `docs/ui-spec/`, and `docs/prd/`. - -Classify discovered documents by filename: -- Filename contains `backend` → **Design Doc (backend)** -- Filename contains `frontend` → **Design Doc (frontend)** -- Located in `docs/ui-spec/` → **UI Spec** (optional) -- Located in `docs/prd/` → **approved PRD / confirmed requirement context** (optional; prefer the path named by the Design Doc) -- None of the above → treat as single-layer Design Doc +Resolve the documents named by `$ARGUMENTS`; when a supplied path is stale, use repository evidence to locate its intended artifact. Use the requested feature and layers as the discovery boundary. Resolve applicable Design Docs and UI Specs/PRDs within that boundary, including same-feature frontend/backend counterparts when fullstack work is requested, even when the named document does not link them. Use feature identity, governing requirements, and implementation ownership to establish relevance; stop once the requested layers and proof boundaries are covered. An explicitly single-layer request remains single-layer. Classify documents from their content and references; filenames are hints. Report an exact missing prerequisite when no applicable Design Doc can be resolved. ### Step 2: Skeleton Generation @@ -61,7 +54,7 @@ Invoke acceptance-test-generator using Agent tool: - `ui_spec`: Existing UI Spec path when present - `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record -Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation before Step 3. +Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. **Expected output**: `generatedFiles` containing integration and e2e paths diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index e9c1207d..9c5d82f2 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -85,7 +85,7 @@ When `adrDecisionPoints` is non-empty: 1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. 2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. ## Step 5: Create the Design Doc diff --git a/dev-workflows/skills/recipe-diagnose/SKILL.md b/dev-workflows/skills/recipe-diagnose/SKILL.md index 25c5da5e..687bd7f1 100644 --- a/dev-workflows/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows/skills/recipe-diagnose/SKILL.md @@ -85,7 +85,7 @@ Review investigation output: - [ ] Each failure point has: `location`, `upstreamDependency`, `symptomExplained`, `causalChain` (reaching a stop condition), `checkStatus`, `evidence` with a `source` citing a specific file or location - [ ] Each failure point has `comparisonAnalysis` (normalImplementation found or explicitly null) - [ ] `causeCategory` for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor -- [ ] `investigationSources` covers at least 3 distinct source types (code, history, dependency, config, document, external) +- [ ] `investigationSources` supplies decisive evidence for the reported causes and scope coverage; material evidence gaps are explicit - [ ] All nodes on mapped paths have been checked (no path was abandoned after finding the first fault) - [ ] `scopeAccounting` accounts for every scope-envelope item as investigated, excluded with governing evidence, or unavailable with its potential effect diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index e44c29e7..acf22580 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -104,7 +104,8 @@ After Structural Scale is determined, follow only that scale's applicable path. - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance diff --git a/dev-workflows/skills/recipe-plan/SKILL.md b/dev-workflows/skills/recipe-plan/SKILL.md index 4c00cca2..af809432 100644 --- a/dev-workflows/skills/recipe-plan/SKILL.md +++ b/dev-workflows/skills/recipe-plan/SKILL.md @@ -53,7 +53,7 @@ Follow the planning process below: ### Step 2: Test Skeleton Generation - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process ### Step 3: Work Plan Creation diff --git a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md index 1a9e20df..5638d79a 100644 --- a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md @@ -24,18 +24,18 @@ Before the first finding disposition, read `references/review-resolution.md` fro **Execution Protocol**: 1. **Invoke named specialists for deliverable production** — pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") -2. **Process one step at a time**: Execute steps sequentially within each unit (2 → 3 → 4 → 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next +2. **Respect evidence dependencies**: Generation precedes verification and review for each unit; revision reruns the affected checks. Independent units may be scheduled without changing these gates. 3. **Preserve evidence while bridging outputs** — copy the fields required by the next specialist in their declared form; apply Review Resolution before routing any correction At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -**Execution Gate**: Complete Phase 1 before Phase 2. Within each phase, complete one unit's generation, verification, review, and required revision to convergence before starting the next unit. Advance only when the current step's stated output and quality gate are satisfied. At each loop boundary, select the first unit in the current phase's declared order whose Unit Completion conditions are unsatisfied and that is not logged as a generation failure. A document path proves generation only. +**Execution Gate**: Each Design Doc depends on its completed parent PRD and scope mapping. Advance each unit only when its stated evidence and Unit Completion conditions are satisfied; a document path proves generation only. Continue independent units when another has a recorded failure, and report incomplete units explicitly. ## Step 0: Initial Configuration ### 0.1 Scope Confirmation -Use AskUserQuestion to confirm: +Use supplied instructions and repository context first. Ask only for missing choices that materially change scope or execution; retain prior authorization and preferences: 1. **Target path**: Which directory/module to document 2. **Depth**: PRD only, or PRD + Design Docs 3. **Reference Architecture**: layered / mvc / clean / hexagonal / none @@ -85,14 +85,16 @@ prompt: | - At least one unit discovered → proceed - No units discovered → ask user for hints - `$STEP_1_OUTPUT.prdUnits` exists -- All `sourceUnits` across `prdUnits` (flattened, deduplicated) match the set of `discoveredUnits` IDs — no unit missing, no unit duplicated -- Each discovered unit's `unitInventory` has at least one non-empty category (routes, testFiles, or publicExports). Units with all three empty indicate incomplete discovery — re-run scope-discoverer with focus on that unit's `relatedFiles` +- Flatten `sourceUnits` across `prdUnits` without deduplication: every discovered ID occurs exactly once, with no unknown IDs +- Each discovered unit has source evidence and an inventory containing the applicable categories; empty categories are valid, but each unit requires at least one behavior-bearing route, public export, or `otherEntryPoints` item with a defining source location. Resolve a material coverage limitation through targeted discovery; preserve non-blocking limitations. **Human Review Point** (if enabled): Present `$STEP_1_OUTPUT.prdUnits` with their source unit mapping. The user confirms, adjusts grouping, or excludes units from scope. This is the most important review point — incorrect grouping cascades into all downstream documents. ### Step 2-5: Per-Unit Processing -**FOR** each unit in `$STEP_1_OUTPUT.prdUnits` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_1_OUTPUT.prdUnits`: + +Derive `$PRD_UNIT_INVENTORY` by joining this PRD unit's `sourceUnits` to `discoveredUnits[].id` and merging their `unitInventory` categories. Deduplicate the merged inventory by item identity (route method/path/owner, test path, export file/name, other entry-point file/name), preserving source evidence. Use this same baseline for generation and verification. #### Step 2: PRD Generation @@ -110,9 +112,10 @@ prompt: | Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged) Related Files: $PRD_UNIT_COMBINED_RELATED_FILES Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS + Unit Inventory: $PRD_UNIT_INVENTORY Use provided scope as investigation starting point. - If tracing entry points reveals files outside this scope, include them. + Inspect dependencies outside these files only when they establish an in-scope behavior or contract; this does not automatically expand feature scope. Create final version PRD based on thorough code investigation. ``` @@ -131,7 +134,7 @@ prompt: | doc_type: prd document_path: $STEP_2_OUTPUT - unit_inventory: [the current unit's Step 1 unitInventory] + unit_inventory: $PRD_UNIT_INVENTORY ``` `unit_inventory` supplies the completeness baseline while repository evidence supplies the search scope. @@ -181,7 +184,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -202,20 +205,22 @@ Each PRD unit from Phase 1 maps to Design Doc unit(s): - **Standard mode (fullstack=No)**: 1 PRD unit → 1 Design Doc (using technical-designer) - **Fullstack mode (fullstack=Yes)**: 1 PRD unit → 2 Design Docs (technical-designer + technical-designer-frontend) -Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward: +For each PRD unit, join its `sourceUnits` to discovered units and merge their technical evidence and inventory, preserving provenance. Map the result to Design Doc targets, carrying forward: - `technicalProfile.primaryModules` → Primary Files - `technicalProfile.publicInterfaces` → Public Interfaces - `dependencies` → Dependencies - `relatedFiles` → Scope boundary -- `unitInventory` → Unit Inventory (routes, test files, public exports) +- `unitInventory` → Unit Inventory (routes, test files, public exports, other entry points) In fullstack mode, partition each unit inventory by the owning path into backend and frontend target inventories. Assign a shared entry to each Design Doc whose public contract must account for it and record that shared reason; otherwise assign it once. Each Step 7 and Step 8 invocation receives its target's inventory, not the unpartitioned combined unit. +Assign each target a distinct `output_path` before generation. Use `[feature]-design.md` in standard mode and `[feature]-backend-design.md` / `[feature]-frontend-design.md` in fullstack mode. Check existing destinations and preserve unrelated artifacts. + **Store output as**: `$STEP_6_OUTPUT` ### Step 7-10: Per-Unit Processing -**FOR** each unit in `$STEP_6_OUTPUT` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_6_OUTPUT`: #### Step 7: Design Doc Generation @@ -238,10 +243,11 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY + output_path: $DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH - Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports should be accounted for in the Design Doc. + Document current architecture as-is. Use Unit Inventory as a completeness baseline — all inventoried capabilities should be accounted for in the Design Doc. ``` **Store output as**: `$STEP_7_OUTPUT` @@ -265,6 +271,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $BACKEND_UNIT_INVENTORY + output_path: $BACKEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH @@ -289,6 +296,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $FRONTEND_UNIT_INVENTORY + output_path: $FRONTEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH Backend Design Doc: $STEP_7a_OUTPUT @@ -371,7 +379,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -394,4 +402,4 @@ Output summary including: |-------|--------| | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | -| Verification is `inconsistent` or inventory remains unaccounted after correction | Flag for mandatory human review — require explicit human approval | +| Required defect remains after Review Resolution | Report the unit incomplete with evidence. A raw verifier label or a resolved decline creates no extra approval gate; optional human review follows Step 0. | diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index 164e91c0..8d8b4390 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows:code-reviewer` or `dev-workflows:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows:code-reviewer" -- `description`: "Re-validate implementation review" -- `prompt`: "Re-review the completed implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md index 253af498..defb3cf7 100644 --- a/dev-workflows/skills/requirement-convergence/SKILL.md +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -1,6 +1,6 @@ --- name: requirement-convergence -description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from decision-relevant repository evidence. Use when a requirement enters a workflow, before design begins. --- # Requirement Convergence @@ -18,7 +18,7 @@ This skill converges **what to build**. How to build it, and which documents the | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | -| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | +| `cost` | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. diff --git a/dev-workflows/skills/requirement-convergence/references/criteria.md b/dev-workflows/skills/requirement-convergence/references/criteria.md index 9d5cbb91..3e8d0727 100644 --- a/dev-workflows/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows/skills/requirement-convergence/references/criteria.md @@ -29,20 +29,9 @@ An adjacent capability the agent noticed stays out of both `requirements[]` and ## cost -Cost follows structure and count, not behavior, so it is decided from these inputs alone: +Estimate rough lifecycle cost from affected responsibilities, contract consumers, reusable behavior, state/migration needs and existing verification support. Inspect enough representative behavior to decide whether an apparent reuse or structural match actually serves the requirement. Use analyzer evidence when supplied. Stop before implementation-level investigation once further detail cannot change scope, cost band or the user decision. -| Input | How it is obtained | -|-------|--------------------| -| Number and kind of targets to change | Grep/Glob over the affected files | -| Number of boundaries crossed | Affected path composition plus import and caller tracing | -| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | -| Whether persisted state needs converting | Whether a schema or migration path is in the change set | -| Whether verification support already exists | Glob for the area's existing test harness | -| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | - -Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. - -Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. +Record `cost` as one evidence-supported band and its remaining unknowns. When an unresolved condition could raise the band, state that condition and the higher-band consequence in the existing cost evidence so scope confirmation exposes the trade-off. A flow declares `cost` out of scope only where its own steps say so. ## Challenge intensity @@ -51,10 +40,10 @@ The band's only job is to select a row here, so cheap requirements stay cheap to | Band | Meaning | Challenge | |------|---------|-----------| | `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | -| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | -| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | +| `medium` | Reverting would touch other work | Present cost and a lower-cost alternative when a materially distinct sufficient option exists | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off; obtain a user decision when a required outcome, explicit constraint or irreversible-action authority must change | -Report an unknown that would move the band up as a blocking question rather than assuming the lower band. +Resolve repository-answerable uncertainty locally. Ask the user only when a remaining unknown changes required scope, constraints or authority; otherwise record its cost effect and keep independent work moving. ## Solution-in-disguise test diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 555c3632..3303e4f7 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -156,7 +156,7 @@ Rules: - When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` - When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported - Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add only their named UI or layer artifact paths +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -204,7 +204,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. + +When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -244,7 +246,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance @@ -282,7 +285,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-03b: applied design-evidence finding → technical-designer - Invoke the owning designer as a fresh `update` call with the existing Design Doc path and complete `correction_findings` objects copied verbatim with only their `apply` dispositions added. - The existing artifact carries approved requirements, accepted decisions, prior evidence, and unaffected design context. Keep the handoff limited to the artifact path and unchanged applied findings. -- The designer applies its review-triggered self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. +- The designer applies its review-triggered bounded self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. @@ -302,8 +305,8 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner - Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. -- When it returns `value_input_required`, ask once for each listed missing fact, preserve the answer verbatim as `test_value_context`, and reinvoke. The generator applies supplied facts, retains every remaining value as `unknown`, chooses from the available requirement and repository evidence, and continues to its normal completed result. -- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, confirm from the Design Doc that no accepted proof obligation requires that boundary, and return an uncovered obligation to the generator for completion. +- Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. +- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. - Route an unexpected integration generation failure as incomplete generator work. A validated null E2E lane is complete. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 289f8bf3..2967d10c 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -77,7 +77,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. - Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per owning-designer invocation serially, and repeats the complete batch review; `rejected` resolves the governing-source conflict before another review. -- Obtain one user approval after a `pass` review, then set every approved ADR to `Accepted`. +- Obtain one user approval after Review Resolution converges and governing-source conflicts are resolved, then set every approved ADR to `Accepted`. - An empty batch proceeds directly to both Design Docs. ## Layer Design Context @@ -88,6 +88,7 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-backend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -98,6 +99,7 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-frontend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -117,7 +119,7 @@ After both document reviews permit approval, invoke design-sync with `source_des ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for `value_input_required` and its unknown-value continuation before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md index 8da4072d..078058c3 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -19,7 +19,7 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. For code-verifier with `unit_inventory`, its full current-document inventory accounting still applies. A decline-only result is complete. ## 1. Assess Every Finding @@ -58,9 +58,9 @@ Select the existing correction owner from the accepted state each finding requir For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. -For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. +For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its review-triggered bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. -For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. +For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. For each ID, preserve the original finding claim and basis verbatim in `evidence`, alongside the correction diff or paths. The correction assessment covers exactly every received item. The reviewer completes that scope and then: @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/dev-workflows/skills/testing-principles/SKILL.md b/dev-workflows/skills/testing-principles/SKILL.md index df9c948f..72579f85 100644 --- a/dev-workflows/skills/testing-principles/SKILL.md +++ b/dev-workflows/skills/testing-principles/SKILL.md @@ -11,6 +11,7 @@ Tests here guarantee accepted behavior, and the next agent reads every existing - Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules. - Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere. +- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary. - Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself. - Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it. diff --git a/package.json b/package.json index 5f091eba..332815a0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.1", + "version": "0.29.2", "private": true, "type": "module", "engines": { diff --git a/skills/ai-development-guide/SKILL.md b/skills/ai-development-guide/SKILL.md index fd97e36d..b3c9e991 100644 --- a/skills/ai-development-guide/SKILL.md +++ b/skills/ai-development-guide/SKILL.md @@ -68,7 +68,7 @@ Make all errors visible and traceable with full context. Prioritize primary code - The same failure is caught at multiple layers without a single recovery owner - Nested handlers obscure which state is committed, rolled back, or exposed - A handler converts a failure to success/default output without an observable degraded-state contract -- Error handlers that return default values without logging +- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal. @@ -143,7 +143,7 @@ Keep concrete implementations separate while their apparent similarity is accide - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis +- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness diff --git a/skills/coding-principles/SKILL.md b/skills/coding-principles/SKILL.md index af2be9c8..bd3ede0b 100644 --- a/skills/coding-principles/SKILL.md +++ b/skills/coding-principles/SKILL.md @@ -70,15 +70,9 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -### Verifying References Before Adoption -When adopting patterns, APIs, or dependencies from existing code: -- **IF** a reference sample covers only nearby files → **THEN** confirm the pattern is representative by checking relevant repository usage before adopting -- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient -- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it -- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update) - -### Principle -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model. +Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations diff --git a/skills/documentation-criteria/references/prd-template.md b/skills/documentation-criteria/references/prd-template.md index d1892ee8..8d814d76 100644 --- a/skills/documentation-criteria/references/prd-template.md +++ b/skills/documentation-criteria/references/prd-template.md @@ -94,6 +94,8 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r ## Success Criteria +State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. + ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] 2. [Metric name]: [numeric target] measured by [method] within [timeframe] @@ -134,7 +136,7 @@ Include only evidenced product or delivery risks that can change scope, success - [ ] [Question 1]: [Description of options or impacts] - [ ] [Question 2]: [Description of options or impacts] -*Discuss with user until this section is empty, then delete after confirmation* +Resolve only questions that block the current document or next decision. Retain non-blocking unknowns with their effect; in as-is documentation, unknown business intent is not a reason to invent requirements. ## Appendix diff --git a/skills/external-resource-context/SKILL.md b/skills/external-resource-context/SKILL.md index 344caaea..1c4da6e7 100644 --- a/skills/external-resource-context/SKILL.md +++ b/skills/external-resource-context/SKILL.md @@ -36,17 +36,17 @@ When the file is absent or the resource is unreachable, continue from governing ## Capturing and Updating Records -Capturing a record requires an interactive hearing. The workflow using this skill owns the interaction mechanism and routing. Follow [references/hearing.md](references/hearing.md) for the hearing conditions, domain routing, two-phase hearing, storage protocol, and quality checklist. +Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow [references/hearing.md](references/hearing.md) for evidence, questions and storage. ## Output Format -The project-tier file follows the structure in [references/template.md](references/template.md). The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically. +Use [references/template.md](references/template.md) for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence. For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context). ## References -- [references/hearing.md](references/hearing.md) — Hearing conditions, domain routing, storage protocol, quality checklist +- [references/hearing.md](references/hearing.md) — Decision-specific capture and storage - [references/frontend.md](references/frontend.md) — Frontend domain axes - [references/backend.md](references/backend.md) — Backend domain axes - [references/api.md](references/api.md) — API contract domain axes diff --git a/skills/external-resource-context/references/api.md b/skills/external-resource-context/references/api.md index b9a3510e..42d2a3db 100644 --- a/skills/external-resource-context/references/api.md +++ b/skills/external-resource-context/references/api.md @@ -1,60 +1,10 @@ -# API Contract Domain Axes +# Api Resource Cues -Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: API Schema Source +- **Schema**: OpenAPI, Protobuf, GraphQL or code-first definition for the affected API. +- **Mock environment**: Existing entry point and whether it preserves the claimed contract. +- **Authentication**: Mechanism and credential-source reference needed for authorized verification. +- **Schema change process**: Versioning or compatibility rule governing the changed contract. -The canonical source of API contracts (request/response shapes, endpoints, RPC methods). - -**Question choices**: -- OpenAPI / Swagger specification (file in repository or hosted URL) -- Protobuf definitions (file in repository) -- GraphQL schema (SDL file or introspection endpoint) -- TypeScript or other code-first contract definitions in the repository -- No formal contract (ad-hoc JSON) -- Not applicable - -**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose. - -## Axis 2: Mock Environment - -How clients exercise the API without depending on the live server. - -**Question choices**: -- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling) -- Hand-written mock server in the repository -- Hosted mock service (URL) -- Live development server (no separate mock) -- Not applicable - -**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes. - -## Axis 3: Authentication Method - -How the API authenticates and authorizes requests. - -**Question choices**: -- Bearer token (e.g., JWT) issued by an auth service -- API key in a header or query parameter -- Session cookie set by a separate login flow -- Mutual TLS -- No authentication -- Not applicable - -**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable. - -## Axis 4: Schema Change Process (When Relevant) - -How breaking and non-breaking schema changes are reviewed and rolled out. - -**Question choices**: -- Documented contract review process (link to the document) -- Versioned endpoints (e.g., `/v1/`, `/v2/`) -- Backward-compatible changes only, no formal versioning -- Not applicable - -**Follow-up (when not N/A)**: Record the document path or the version negotiation rule. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/skills/external-resource-context/references/backend.md b/skills/external-resource-context/references/backend.md index ffc27403..2d9c0535 100644 --- a/skills/external-resource-context/references/backend.md +++ b/skills/external-resource-context/references/backend.md @@ -1,60 +1,10 @@ -# Backend Domain Axes +# Backend Resource Cues -Hearing axes for tasks that involve server-side, data, or storage work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Database Schema Source +- **Database schema**: Authoritative migration, schema file or registry for the affected contract. +- **Migration history**: Relevant tool and history when state conversion affects the decision. +- **Secret store**: Location and retrieval mechanism only; keep secret values out of records. +- **Background jobs**: Queue or scheduler and inspection method when delivery behavior matters. -The canonical source of the database schema (tables, columns, indexes, constraints). - -**Question choices**: -- Migration files in the repository (e.g., a `migrations/` directory) -- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`) -- Database MCP that introspects a live database -- External schema registry (URL or hosted catalog) -- No persistent database -- Not applicable - -**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each. - -## Axis 2: Migration History - -How schema changes are tracked over time. - -**Question choices**: -- Versioned migration files in the repository -- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate) -- Manual change log document -- No migration tracking -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually. - -## Axis 3: Secret Store - -Where credentials, API keys, and other secrets are stored and accessed. - -**Question choices**: -- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager) -- Environment variables loaded from a `.env` file (development only) -- Encrypted file in the repository -- No secrets required -- Not applicable - -**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached. - -## Axis 4: Background Job Infrastructure (When Relevant) - -How asynchronous work is dispatched and observed. - -**Question choices**: -- Queue service (e.g., SQS, Pub/Sub, RabbitMQ) -- Cron / scheduled tasks managed by deployment platform -- In-process worker thread -- No background work -- Not applicable - -**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/skills/external-resource-context/references/frontend.md b/skills/external-resource-context/references/frontend.md index b90b4e29..76ae7d6e 100644 --- a/skills/external-resource-context/references/frontend.md +++ b/skills/external-resource-context/references/frontend.md @@ -1,60 +1,10 @@ -# Frontend Domain Axes +# Frontend Resource Cues -Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration). +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: Design Origin +- **Design origin**: Canonical visual source or specification and the applicable node/version. +- **Design system**: Component/token documentation or package that determines this UI contract. +- **Guidelines**: A sourced usage or accessibility requirement that constrains this change. +- **Visual verification**: Existing rendering entry point, harness or access method needed to observe the UI. -The canonical source of the visual specification. - -**Question choices**: -- Design tool (e.g., a hosted design platform) -- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`) -- Public documentation URL -- Existing implementation only (no separate design source) -- Not applicable - -**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism. - -## Axis 2: Design System - -Reusable component library and design tokens. - -**Question choices**: -- Component library with MCP server access -- Component library with documentation URL -- Storybook or equivalent component catalog -- Internal package without external documentation -- No design system (ad-hoc components) -- Not applicable - -**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name. - -## Axis 3: Guidelines - -Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work. - -**Question choices**: -- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`) -- External documentation site -- Inline guidance in the design system catalog -- No documented guidelines -- Not applicable - -**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each. - -## Axis 4: Visual Verification Environment - -How rendered output is confirmed during implementation. - -**Question choices**: -- End-to-end test runner with screenshot capability -- Storybook or equivalent isolated component preview -- Browser automation tool (dedicated CLI or MCP server) -- Manual browser inspection only -- Not applicable - -**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/skills/external-resource-context/references/hearing.md b/skills/external-resource-context/references/hearing.md index e81156f3..971c0bc2 100644 --- a/skills/external-resource-context/references/hearing.md +++ b/skills/external-resource-context/references/hearing.md @@ -1,52 +1,18 @@ -# External Resource Hearing and Storage +# External Resource Capture -Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism. +Capture a resource only when repository and supplied evidence cannot decide a current design, implementation or verification question without it. Absence of a project record does not trigger a domain-wide questionnaire. -## When to Hear +## Resolve Access -| Condition | Action | -|-----------|--------| -| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) | -| File exists and covers the current decision | Use it without an update question | -| The governing request identifies changed environment facts | Run diff-only hearing for the named axes | -| A relevant axis is absent | Hear only the missing axis | -| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation | +1. Name the decision and required external fact. Read the existing project entry and feature identifier when available. +2. Reuse access details from the user, governing artifacts or repository configuration. Fetch the selected content within current authority. A new record can be written from this evidence without a hearing. +3. Ask only for a missing location, access method or user-owned interpretation that prevents the decision. The calling workflow owns interaction; an autonomous consumer returns the exact missing evidence to that caller and continues independent work. +4. Correct stale details when authoritative current evidence establishes the replacement. When it does not, preserve the last known record, report the failed access and ask only for the unresolved decision-relevant fact. Record locations and access mechanisms, never secret values. -## Domain Routing +## Optional Domain Cues -Load the domain reference matching the current task: +Load only the reference needed to locate the selected fact: [frontend.md](frontend.md), [backend.md](backend.md), [api.md](api.md), or [infra.md](infra.md). Their lists are cues, not required questions or completion axes. -| Task type | References to load | -|-----------|--------------------| -| Frontend (UI work) | [frontend.md](frontend.md) | -| Backend (server / data work) | [backend.md](backend.md) | -| API contract work | [api.md](api.md) | -| Infrastructure / deployment | [infra.md](infra.md) | -| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure | +## Store -Each domain reference defines the axes and the question template. - -## Two-Phase Hearing - -1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command). - -2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration. - -For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis. - -## Storage Protocol - -After hearing completes: - -1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure. -2. Write to `docs/project-context/external-resources.md`. Create the directory if absent. -3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only). -4. Report the file paths back to the calling workflow. - -## Quality Checklist - -- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable" -- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes -- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command) -- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier -- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision +Use [template.md](template.md) for `docs/project-context/external-resources.md`. Keep environment facts at project level and feature-specific identifiers in the consuming document's `External Resources Used` table. Preserve unrelated entries and stable labels. Create no empty record or N/A catalog when no external source is required. Return changed paths and any exact remaining evidence limitation to the caller. diff --git a/skills/external-resource-context/references/infra.md b/skills/external-resource-context/references/infra.md index 932a416d..0529df4d 100644 --- a/skills/external-resource-context/references/infra.md +++ b/skills/external-resource-context/references/infra.md @@ -1,60 +1,10 @@ -# Infrastructure Domain Axes +# Infra Resource Cues -Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work. +Consult only entries that can resolve the current question. Supplied and repository evidence come first; ask for missing access details only when required. -## Axis 1: IaC Source +- **IaC source**: Relevant checked-in or external infrastructure definition. +- **Environment configuration**: Configuration source for the specific environment and question. +- **Secrets**: Secret-store reference and access mechanism, never values. +- **Deployment trigger**: Existing execution/approval boundary only when it affects current implementation or verification. -The canonical source of infrastructure definitions. - -**Question choices**: -- Terraform configuration in the repository -- Pulumi or CDK code in the repository -- Kubernetes manifests / Helm charts in the repository -- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager) -- Manual console configuration (no IaC) -- Not applicable - -**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually. - -## Axis 2: Environment Configuration - -How per-environment settings (development, staging, production) differ. - -**Question choices**: -- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`) -- Environment variables managed by the deployment platform -- Workspace or stack abstraction in the IaC tool itself -- Single shared configuration (no per-environment differences) -- Not applicable - -**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist. - -## Axis 3: Secrets in Infrastructure - -How infrastructure code references secrets without exposing them. - -**Question choices**: -- Secrets sourced from a secret manager via IaC data lookup -- Secrets injected at apply time via environment variables -- Encrypted secret files committed alongside IaC -- No secrets in infrastructure -- Not applicable - -**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC. - -## Axis 4: Deployment Trigger - -How infrastructure and application changes reach environments. - -**Question choices**: -- CI pipeline triggered on merge to a specific branch -- Manual approval step in CI -- Local apply by an operator -- Deployment platform's auto-deploy on push -- Not applicable - -**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment. - -## Domain Completion - -After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer. +Return the selected resource and evidence to the parent capture protocol. These cues create no obligation to survey unrelated resources. diff --git a/skills/external-resource-context/references/template.md b/skills/external-resource-context/references/template.md index 169f3b29..8321a7ac 100644 --- a/skills/external-resource-context/references/template.md +++ b/skills/external-resource-context/references/template.md @@ -1,115 +1,31 @@ # Storage Templates -Two templates: the project-tier file and the feature-tier section. +## Project Record -## Project-Tier Template - -Path: `docs/project-context/external-resources.md` +Path: `docs/project-context/external-resources.md`. Preserve existing resource labels referenced by feature documents. Include only resources actually needed; adapt grouping to the existing file. ```markdown # External Resources -Last updated: YYYY-MM-DD - -This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only. - -## Frontend - -### Design Origin -- Status: -- Source type: -- Location: -- Access method: - -### Design System -- Status: -- Source type: -- Location: -- Access method: - -### Guidelines -- Status: -- Source type: -- Location: -- Access method: - -### Visual Verification Environment -- Status: -- Tool type: -- Entry: - -## Backend - -### Database Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Migration History -- Status: -- Tool: -- Location: -- Apply trigger: - -### Secret Store -- Status: -- Service: -- Access method: - -### Background Job Infrastructure -- Status: -- Service: -- Access method: - -## API - -### API Schema Source -- Status: -- Source type: -- Location: -- Access method: - -### Mock Environment -- Status: -- Source type: -- Entry: - -### Authentication Method -- Status: -- Mechanism: -- Credential source: - -### Schema Change Process -- Status: -- Process: - -## Infrastructure - -### IaC Source -- Status: -- Tool: -- Location: -- Apply trigger: - -### Environment Configuration -- Status: -- Mechanism: -- Environments: +## [Stable resource label] +- Purpose: [decision or contract served] +- Location: [URL, path, package or service] +- Access method: [read operation, tool or command within existing authority] +- Evidence: [source and relevant version/date] +``` -### Secrets in Infrastructure -- Status: -- Mechanism: +Keep credentials and secret values outside this record. Record an access limitation when it affects a consumer; a failed fetch does not establish that the resource is absent. -### Deployment Trigger -- Status: -- Mechanism: +## Feature Reference -## Additional Resources +Use the consuming document's natural heading level for `External Resources Used`. -Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method. +```markdown +## External Resources Used -- : — — +| Project resource label | Feature-specific identifier | Use | +|---|---|---| +| [existing label] | [node, endpoint, module or version selector] | [decision or proof] | ``` -Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline). +Project entries own shared locations and access methods; feature rows own only the subset and identifiers used here. diff --git a/skills/integration-e2e-testing/SKILL.md b/skills/integration-e2e-testing/SKILL.md index 53987b3b..aa037f1f 100644 --- a/skills/integration-e2e-testing/SKILL.md +++ b/skills/integration-e2e-testing/SKILL.md @@ -1,121 +1,17 @@ --- name: integration-e2e-testing -description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria. Use when designing integration tests, E2E tests, or reviewing test quality. +description: Defines integration/E2E skeleton annotations, lane and file contracts, and route-parity review criteria. Use when generating or consuming test skeletons or reviewing shared mutation routes. --- -# Integration and E2E Testing Principles +# Integration and E2E Skeleton Contracts -## References +## Test Lanes -**E2E test design**: See [references/e2e-design.md](references/e2e-design.md) for UI Spec-driven E2E test candidate selection. - -## Test Type Definition and Standard Budgets - -| Test Type | Purpose | Scope | External Deps | Standard Budget per Input Design Doc | Implementation Timing | -|-----------|---------|-------|---------------|-------------------|----------------------| -| Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | -| fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | - -**Lane selection (E2E only)**: -- Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup -- Add **service-integration-e2e** only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely - -One input Design Doc is one budget scope: apply each lane budget once across all ACs and candidates in that document. The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa. Treat the numbers above as enforced standard budgets. Exceed a budget only when an accepted requirement or a distinct failure mode cannot be proved by a selected test; annotate that exception and why consolidation cannot cover it. - -## Behavior-First Principle - -### Include (High ROI) -- Business state transitions observable across components -- Data integrity and persistence behavior -- User-visible functionality completeness -- Error handling behavior (what user sees/experiences) - -### Redirect to Other Test Types -- Calculation and data transformation rules → Verify via unit tests of the logic that owns them -- External service connections → Verify via contract/interface tests -- Performance metrics → Verify via dedicated load testing -- Implementation details → Verify observable behavior instead -- UI layout specifics → Verify information availability instead - -**Principle**: Test = User-observable behavior verifiable in isolated CI environment - -## ROI Calculation - -ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently. - -For every candidate, record the governing evidence for each ROI input before assigning a value. Use an approved PRD, confirmed requirement context, accepted contract or legal obligation, user-confirmed test value context, Design Doc boundary, and existing-test evidence as applicable. A missing value is `unknown`, not `0`, and an inference is not observed evidence. - -When ROI can change candidate ranking, a lane threshold, or budget selection, return the exact missing product input and its decision effect when `test_value_context` has not yet supplied it. After that single input round, apply the supplied facts and retain every remaining value as decision-relevant `unknown` with its numeric score unset. Resolve Defect Detection from repository evidence at the proof boundary and in existing tests. When selection is invariant because the candidate is removed before ROI, is the sole eligible candidate for a reserved journey slot, or all surviving candidates fit an unthresholded budget, record the unknown as `not_decision_relevant` and keep its numeric score unset. - -### Unknown-Value Ordering - -For candidates with a decision-relevant `unknown` after the value-input round, use accepted legal or contractual obligation, explicit connection to the confirmed user or business outcome, distinct Defect Detection evidence, lower lane ownership cost, then source AC order. Select the smallest set that proves the accepted obligations and confirmed outcome boundaries, within the normal lane budgets. Numeric lane thresholds apply to fully scored candidates; this evidence ordering supplies the selection decision for affected candidates. Record the unknown input, evidence checked, and selection effect. - -For resolved numeric inputs, use exactly `0`, `5`, or `10`. Legal Requirement remains boolean; a governing-source check that finds no accepted legal, regulatory, contractual, or audit obligation supports `false` and records that checked source. - -| Input | Scale | -|---|---| -| Business Value | 0 = no user/business outcome; 5 = meaningful but non-critical outcome; 10 = core, revenue, safety, or data-integrity outcome | -| User Frequency | 0 = unreachable/obsolete; 5 = regular subset of users or runs; 10 = dominant journey or execution path | -| Legal Requirement | `true` only when an accepted legal, regulatory, contractual, or audit requirement applies; otherwise `false` | -| Defect Detection | 0 = duplicates existing proof; 5 = covers a distinct branch/state; 10 = uniquely detects a critical boundary or cross-service failure | - -``` -ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection - (range: 0–120) -``` - -Higher ROI Score = higher priority within its test type. For equal scores, order by Legal Requirement (`true` first), then higher Defect Detection, Business Value, User Frequency, and finally source AC order. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores. - -### ROI Thresholds by Lane - -The two E2E lanes have different ownership costs and use independent standard thresholds. - -| Lane | ROI threshold | Rationale | -|------|---------------|-----------| -| fixture-e2e | ROI ≥ 20 (beyond reserved slot) | Cost is comparable to integration tests once the harness exists; the floor avoids filling MAX 3 with low-signal tests when fewer would suffice | -| service-integration-e2e | ROI > 50 (beyond reserved slot) | Live-service setup, state cleanup, and failure diagnosis add material ownership cost; reserve for journeys whose value cannot be proven any other way | - -Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Emit a below-floor candidate beyond the reserved slot only when an accepted requirement or a distinct uncovered failure mode justifies the exception. Leave budget intentionally unfilled rather than padding with low-value tests; record any threshold or budget exception in the skeleton that carries the exception. - -### ROI Calculation Examples - -| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome | -|----------|----|------|-------|--------|-----------|-----------|-------------------| -| Core checkout UI flow | 10 | 10 | true | 10 | 120 | fixture-e2e | Selected (reserved slot: user-facing multi-step journey, browser-level verification with fixtures) | -| Core checkout against live payment service | 10 | 10 | true | 10 | 120 | service-integration-e2e | Selected (real-service correctness above ROI threshold) | -| Dismiss button updates UI state | 5 | 10 | false | 5 | 55 | fixture-e2e | Selected (rank 2 of 3 fixture-e2e budget) | -| Payment error message display | 5 | 5 | false | 5 | 30 | fixture-e2e | Selected (rank 3 of 3 fixture-e2e budget) | -| Optional filter toggle | 5 | 5 | false | 0 | 25 | fixture-e2e | Removed during deduplication (duplicates existing proof) | -| Payment retry against real provider | 5 | 5 | false | 5 | 30 | service-integration-e2e | Below ROI threshold (30 < 50), not selected | -| DB persistence check | 10 | 5 | false | 10 | 60 | Integration | Selected (rank 1 of 3) | -| Pure data transformation | 5 | 5 | false | 5 | 30 | Unit | Not selected (push down to unit test) | - -## Multi-Step User Journey Definition - -A candidate qualifies as a **multi-step user journey** when ALL of the following are true: - -1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type: - - Web: distinct routes/pages - - Mobile native: distinct screens/views - - CLI: distinct command invocations or interactive prompts - - API: distinct API calls forming a transaction (e.g., create → confirm → finalize) -2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays -3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow) - -### User-Facing vs Service-Internal Journeys - -Multi-step journeys are classified for reserved-slot eligibility: - -| Classification | Condition | Reserved Slot Eligibility | Example | -|---|---|---|---| -| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible — defaults to **fixture-e2e** reserved slot. Add a service-integration-e2e reserved slot only when the journey's correctness depends on real cross-service behavior | Web checkout flow, CLI setup wizard, mobile onboarding | -| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot — use integration tests. Service-integration-e2e through normal ROI > 50 path is still valid when full-system verification is warranted | Async job pipeline, service-to-service saga, scheduled batch processing | - -This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above. - -Use this definition when evaluating E2E test candidates and E2E gap detection. +| Lane | Observable boundary | Dependencies | +|------|---------------------|--------------| +| `integration` | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary | +| `fixture-e2e` | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary | +| `service-integration-e2e` | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary | ## Test Skeleton Specification @@ -126,18 +22,11 @@ Each test MUST include the following annotations: ``` AC: [Original acceptance criteria text] Behavior: [Trigger] → [Process] → [Observable Result] -@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e @lane: integration | fixture-e2e | service-integration-e2e @dependency: none | [component names] | full-system -@complexity: low | medium | high -ROI: [score] +Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient] ``` -**`@lane` selection rule**: -- `integration` — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language) -- `fixture-e2e` — Browser-level UI verification with mocked backend / fixture-driven state -- `service-integration-e2e` — Browser-level or end-to-end verification against running local services or stubs - Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). ### Verification Items (Optional) @@ -149,33 +38,14 @@ Verification items: - [Item 2] ``` -## EARS Format Mapping - -| EARS Keyword | Test Type | Generation Approach | -|--------------|-----------|---------------------| -| **When** | Event-driven | Trigger event → verify outcome | -| **While** | State condition | Setup state → verify behavior | -| **If-then** | Branch coverage | Both condition paths verified | -| (none) | Basic functionality | Direct invocation → verify result | - ## Test File Naming Convention - Integration tests: `*.int.test.*` or `*.integration.test.*` - fixture-e2e tests: `*.fixture.e2e.test.*` (or organize under `tests/e2e/fixture/`) - service-integration-e2e tests: `*.service.e2e.test.*` (or organize under `tests/e2e/service/`) -The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing and budget accounting. - -## Review Criteria - -### Skeleton and Implementation Consistency - -| Check | Failure Condition | -|-------|-------------------| -| Behavior Verification | No assertion for "observable result" in the implemented test | -| Verification Item Coverage | Listed items not all covered by assertions | -| Mock Boundary | Internal components mocked in integration test | +The test runner or framework in the project determines the appropriate file extension. Repos that already use a single `*.e2e.test.*` convention may keep it as long as each file declares `@lane:` in its header — the lane annotation is the source of truth for routing. -### Route Parity for Shared Mutations +## Route Parity for Shared Mutations -When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure. diff --git a/skills/integration-e2e-testing/references/e2e-design.md b/skills/integration-e2e-testing/references/e2e-design.md deleted file mode 100644 index 7c1e95a0..00000000 --- a/skills/integration-e2e-testing/references/e2e-design.md +++ /dev/null @@ -1,72 +0,0 @@ -# E2E Test Design (Browser Harness) - -This reference uses Playwright as the default browser harness. Adapt patterns to the project's chosen framework when different (Cypress, Selenium, etc.); the lane definitions, ROI rules, and budgets remain the same. - -## Two E2E Lanes - -E2E tests in this workflow split into two lanes (see parent skill Test Type Definition): - -| Lane | When | ROI gate | Cost | -|------|------|----------|------| -| **fixture-e2e** | UI journey verification with deterministic fixtures (mocked backend / fixture data) | ROI ≥ 20 (beyond reserved slot); selected by ranking within MAX 3 budget | Comparable to integration; runs in CI without infrastructure setup | -| **service-integration-e2e** | Journey correctness depends on real cross-service behavior (data persistence, transactional consistency, external contracts) | ROI > 50 (beyond reserved slot) | Higher setup, state-cleanup, and diagnosis cost; reserved for what cannot be faked safely | - -The **reserved slot** referenced in the ROI gates is a per-lane slot for a qualifying multi-step user journey that is emitted regardless of its ROI score; it is defined in the parent skill's *Multi-Step User Journey Definition* section. - -## When to Create E2E Tests - -E2E candidates target **critical user journeys** that span multiple pages or require real browser interaction. Pick the lane based on whether real services are required for the verification. - -### Candidate Sources - -| Source | What to Extract | -|--------|----------------| -| **Design Doc ACs** | User journeys with EARS "When" keyword spanning multiple screens | -| **UI Spec Screen Transitions** | Multi-step flows (e.g., form wizard, checkout) | -| **UI Spec State x Display Matrix** | Error/empty/loading states requiring browser-level verification | -| **UI Spec Interaction Definitions** | Complex interactions (drag-drop, keyboard navigation, responsive behavior) | - -### Selection Criteria - -**Include** (high E2E ROI): -- Multi-page user journeys (login → dashboard → action → confirmation) -- Flows requiring real browser APIs (navigation, cookies, localStorage) -- Accessibility verification requiring actual DOM rendering -- Responsive behavior across viewports - -**Use integration tests instead when**: -- Testing single-component state changes → in-process component renderer (e.g., RTL for React/TS) -- Testing API response handling → in-process API mock + component renderer (e.g., MSW + RTL for React/TS) -- Testing pure data transformations → unit tests - -## UI Spec to E2E Test Mapping - -When a UI Spec exists, use it as the primary source for E2E test design: - -1. **Extract screen transitions** → Each multi-step transition = 1 E2E candidate -2. **Check state x display matrix** → Error states requiring navigation = E2E candidate -3. **Review interaction definitions** → Browser-dependent interactions = E2E candidate -4. **Cross-reference with Design Doc ACs** → Ensure E2E candidates map to acceptance criteria - -### Mapping Template - -``` -Screen Transition: [Screen A] → [Screen B] → [Screen C] -AC Reference: AC-{id} -User Journey: [Description of what the user accomplishes] -Lane: fixture-e2e | service-integration-e2e -Preconditions: [Auth state, data state — note whether these are fixture-driven or live] -Verification Points: - - [What to assert at each step] -E2E ROI Score: [calculated score] -``` - -**Lane decision**: choose `fixture-e2e` by default. Promote to `service-integration-e2e` when the verification requires observing real cross-service behavior (e.g., the test asserts that data persists across a real DB write, or that an external service receives the correct payload). - -## Budget Enforcement - -Standard budgets per input Design Doc (same as parent skill): -- **fixture-e2e**: MAX 3 tests, ROI ≥ 20 beyond the reserved slot (selected by ranking) -- **service-integration-e2e**: MAX 1-2 tests, ROI > 50 beyond the reserved slot -- Prefer fewer, comprehensive journey tests over many granular tests in both lanes -- Exceed a standard budget only for an accepted requirement or distinct uncovered failure mode, and record why the selected tests cannot be consolidated diff --git a/skills/llm-friendly-context/SKILL.md b/skills/llm-friendly-context/SKILL.md index 73cc23e6..6ff8fcf1 100644 --- a/skills/llm-friendly-context/SKILL.md +++ b/skills/llm-friendly-context/SKILL.md @@ -16,7 +16,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Example: "Preserve existing public API behavior across the documented compatibility cases." 2. **Make vague instructions concrete** - - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules. + - Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions. - Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`. 3. **Specify output shape** @@ -30,7 +30,7 @@ The goal is stable downstream execution: the next consumer should know what to r - Follow references while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - - Split work with 3+ objectives or sequential dependencies into ordered steps. + - Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task. - Each step needs a checkpoint: what evidence proves it is complete. 6. **Permit uncertainty explicitly** @@ -40,7 +40,7 @@ The goal is stable downstream execution: the next consumer should know what to r 7. **Keep constraints proportionate** - Add only constraints that reduce ambiguity or preserve a real requirement. - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear. - - Apply `minimal`, `a few lines`, and explicit line estimates to the completed diff as one total budget. + - Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count. ## Rewrite Patterns @@ -49,7 +49,7 @@ Use these rewrites before treating a prompt, handoff, or artifact as complete. | Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | -| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule | +| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | @@ -68,7 +68,7 @@ Before sending a prompt or artifact to another consumer, verify: - [ ] Accepted decisions and constraints use one canonical wording. - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. -- [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains. - [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative. - [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner. diff --git a/skills/recipe-add-integration-tests/SKILL.md b/skills/recipe-add-integration-tests/SKILL.md index 2a4f473e..479d208a 100644 --- a/skills/recipe-add-integration-tests/SKILL.md +++ b/skills/recipe-add-integration-tests/SKILL.md @@ -43,14 +43,7 @@ Document paths: $ARGUMENTS ### Step 1: Discover and Validate Documents -Confirm `$ARGUMENTS` names at least one existing document path; report and end when it is empty or every path is unresolvable. Then discover the remaining Design Docs, UI Specs, and PRDs under `docs/design/`, `docs/ui-spec/`, and `docs/prd/`. - -Classify discovered documents by filename: -- Filename contains `backend` → **Design Doc (backend)** -- Filename contains `frontend` → **Design Doc (frontend)** -- Located in `docs/ui-spec/` → **UI Spec** (optional) -- Located in `docs/prd/` → **approved PRD / confirmed requirement context** (optional; prefer the path named by the Design Doc) -- None of the above → treat as single-layer Design Doc +Resolve the documents named by `$ARGUMENTS`; when a supplied path is stale, use repository evidence to locate its intended artifact. Use the requested feature and layers as the discovery boundary. Resolve applicable Design Docs and UI Specs/PRDs within that boundary, including same-feature frontend/backend counterparts when fullstack work is requested, even when the named document does not link them. Use feature identity, governing requirements, and implementation ownership to establish relevance; stop once the requested layers and proof boundaries are covered. An explicitly single-layer request remains single-layer. Classify documents from their content and references; filenames are hints. Report an exact missing prerequisite when no applicable Design Doc can be resolved. ### Step 2: Skeleton Generation @@ -61,7 +54,7 @@ Invoke acceptance-test-generator using Agent tool: - `ui_spec`: Existing UI Spec path when present - `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record -Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation before Step 3. +Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. **Expected output**: `generatedFiles` containing integration and e2e paths diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index e9c1207d..9c5d82f2 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -85,7 +85,7 @@ When `adrDecisionPoints` is non-empty: 1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. 2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. ## Step 5: Create the Design Doc diff --git a/skills/recipe-diagnose/SKILL.md b/skills/recipe-diagnose/SKILL.md index 25c5da5e..687bd7f1 100644 --- a/skills/recipe-diagnose/SKILL.md +++ b/skills/recipe-diagnose/SKILL.md @@ -85,7 +85,7 @@ Review investigation output: - [ ] Each failure point has: `location`, `upstreamDependency`, `symptomExplained`, `causalChain` (reaching a stop condition), `checkStatus`, `evidence` with a `source` citing a specific file or location - [ ] Each failure point has `comparisonAnalysis` (normalImplementation found or explicitly null) - [ ] `causeCategory` for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor -- [ ] `investigationSources` covers at least 3 distinct source types (code, history, dependency, config, document, external) +- [ ] `investigationSources` supplies decisive evidence for the reported causes and scope coverage; material evidence gaps are explicit - [ ] All nodes on mapped paths have been checked (no path was abandoned after finding the first fault) - [ ] `scopeAccounting` accounts for every scope-envelope item as investigated, excluded with governing evidence, or unavailable with its potential effect diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 8090c726..d7bddcd1 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -16,7 +16,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Execution Protocol**: 1. **Delegate to subagents** (one-shot calls): quality-fixer-frontend. -2. **Run in the parent session** (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. +2. **Run in the parent session** (multi-step loops and user dialogs): conditional external-evidence resolution, with AskUserQuestion for missing decision-relevant inputs, write-set inspection, scale judgment, adjustment-context approval, adjustment edits, verification against the design source, iteration until acceptance. 3. **Stop at every `[Stop: ...]` marker** before proceeding. ## Execution Gate @@ -44,7 +44,7 @@ Adjustment request → conditional external resource evidence ## Scope Boundaries **Included in this skill**: -- External resource hearing per the external-resource-context skill +- Conditional external-evidence resolution per the external-resource-context skill - Existing-pattern and write-set inspection in the parent session - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) @@ -59,10 +59,10 @@ Adjustment request: $ARGUMENTS ## Execution Flow -### Step 1: External Resource Hearing -Execute Skill: external-resource-context before running the hearing protocol. +### Step 1: External Resource Evidence +Execute Skill: external-resource-context when external evidence is required. -Run the hearing protocol only when external evidence can change the current adjustment target or verification result. Otherwise continue with the existing repository/UI Spec evidence and record no external references. +Resolve only external evidence that can change the current adjustment target or verification result; use existing access details and ask only for missing decision-relevant inputs. Otherwise continue with the existing repository/UI Spec evidence and record no external references. ### Step 2: Determine the Route and Write Set @@ -99,14 +99,11 @@ Execute Skill: testing-principles before adding or changing tests. Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: - - Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path) - - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) +3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. 5. When the complete adjustment matches the confirmed target, proceed to Step 6. -When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. +When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. ### Step 6: Quality Verification @@ -132,7 +129,7 @@ On continuation, reconstruct retained limitations from the verification trailers ## Completion Criteria -- [ ] External resource hearing executed (project-tier file written or update explicitly skipped) +- [ ] Decision-relevant external evidence was resolved or its exact limitation retained; no record is required when repository/UI Spec evidence suffices - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 7a86fcbb..9cc6eafb 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -113,7 +113,7 @@ When `adrDecisionPoints` is non-empty: 1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. 2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. -4. Present one batch decision only after a `pass` review. `[Stop: ADR batch approval]`. +4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. ## Step 7: Create the Frontend Design Doc @@ -132,6 +132,8 @@ Invoke `dev-workflows-frontend:technical-designer-frontend` with exactly: The Design Doc owns the full component-to-service implementation and retains all applicable downstream safeguards. +When a backend Design Doc already exists for this feature, pass a distinct `output_path` such as `docs/design/[feature-name]-frontend-design.md`; preserve the backend path as a reference. + ## Step 8: Verify, Review, and Approve Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. diff --git a/skills/recipe-front-plan/SKILL.md b/skills/recipe-front-plan/SKILL.md index 4089abae..72304ac6 100644 --- a/skills/recipe-front-plan/SKILL.md +++ b/skills/recipe-front-plan/SKILL.md @@ -59,7 +59,7 @@ Follow the planning process below: - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner ### Step 3: Work Plan Creation diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index ce6da1a0..c6f0aa6c 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer-frontend result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows-frontend:code-reviewer` or `dev-workflows-frontend:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows-frontend:code-reviewer" -- `description`: "Re-validate frontend implementation review" -- `prompt`: "Re-review the completed frontend implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows-frontend:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index 82da5b91..dc9056c6 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -66,7 +66,7 @@ Key points to enforce as the orchestrator runs the flow: - Execute document-reviewer once per Design Doc (separate invocations) - Run design-sync for cross-layer consistency verification - Pass all Design Docs to work-planner (subagent_type: "dev-workflows:work-planner") with vertical slicing instruction -- Pass the Work Plan to document-reviewer (`doc_type: WorkPlan`) and request batch approval only after the review passes +- Pass the Work Plan to document-reviewer (`doc_type: WorkPlan`) and request batch approval after Review Resolution converges and governing-source conflicts are resolved ### 4. Bind the Applicable Flow diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index e44c29e7..acf22580 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -104,7 +104,8 @@ After Structural Scale is determined, follow only that scale's applicable path. - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance diff --git a/skills/recipe-plan/SKILL.md b/skills/recipe-plan/SKILL.md index 4c00cca2..af809432 100644 --- a/skills/recipe-plan/SKILL.md +++ b/skills/recipe-plan/SKILL.md @@ -53,7 +53,7 @@ Follow the planning process below: ### Step 2: Test Skeleton Generation - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - - Follow subagents-orchestration-guide HC-06 for `value_input_required` and its unknown-value continuation + - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process ### Step 3: Work Plan Creation diff --git a/skills/recipe-reverse-engineer/SKILL.md b/skills/recipe-reverse-engineer/SKILL.md index 1a9e20df..5638d79a 100644 --- a/skills/recipe-reverse-engineer/SKILL.md +++ b/skills/recipe-reverse-engineer/SKILL.md @@ -24,18 +24,18 @@ Before the first finding disposition, read `references/review-resolution.md` fro **Execution Protocol**: 1. **Invoke named specialists for deliverable production** — pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") -2. **Process one step at a time**: Execute steps sequentially within each unit (2 → 3 → 4 → 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next +2. **Respect evidence dependencies**: Generation precedes verification and review for each unit; revision reruns the affected checks. Independent units may be scheduled without changing these gates. 3. **Preserve evidence while bridging outputs** — copy the fields required by the next specialist in their declared form; apply Review Resolution before routing any correction At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -**Execution Gate**: Complete Phase 1 before Phase 2. Within each phase, complete one unit's generation, verification, review, and required revision to convergence before starting the next unit. Advance only when the current step's stated output and quality gate are satisfied. At each loop boundary, select the first unit in the current phase's declared order whose Unit Completion conditions are unsatisfied and that is not logged as a generation failure. A document path proves generation only. +**Execution Gate**: Each Design Doc depends on its completed parent PRD and scope mapping. Advance each unit only when its stated evidence and Unit Completion conditions are satisfied; a document path proves generation only. Continue independent units when another has a recorded failure, and report incomplete units explicitly. ## Step 0: Initial Configuration ### 0.1 Scope Confirmation -Use AskUserQuestion to confirm: +Use supplied instructions and repository context first. Ask only for missing choices that materially change scope or execution; retain prior authorization and preferences: 1. **Target path**: Which directory/module to document 2. **Depth**: PRD only, or PRD + Design Docs 3. **Reference Architecture**: layered / mvc / clean / hexagonal / none @@ -85,14 +85,16 @@ prompt: | - At least one unit discovered → proceed - No units discovered → ask user for hints - `$STEP_1_OUTPUT.prdUnits` exists -- All `sourceUnits` across `prdUnits` (flattened, deduplicated) match the set of `discoveredUnits` IDs — no unit missing, no unit duplicated -- Each discovered unit's `unitInventory` has at least one non-empty category (routes, testFiles, or publicExports). Units with all three empty indicate incomplete discovery — re-run scope-discoverer with focus on that unit's `relatedFiles` +- Flatten `sourceUnits` across `prdUnits` without deduplication: every discovered ID occurs exactly once, with no unknown IDs +- Each discovered unit has source evidence and an inventory containing the applicable categories; empty categories are valid, but each unit requires at least one behavior-bearing route, public export, or `otherEntryPoints` item with a defining source location. Resolve a material coverage limitation through targeted discovery; preserve non-blocking limitations. **Human Review Point** (if enabled): Present `$STEP_1_OUTPUT.prdUnits` with their source unit mapping. The user confirms, adjusts grouping, or excludes units from scope. This is the most important review point — incorrect grouping cascades into all downstream documents. ### Step 2-5: Per-Unit Processing -**FOR** each unit in `$STEP_1_OUTPUT.prdUnits` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_1_OUTPUT.prdUnits`: + +Derive `$PRD_UNIT_INVENTORY` by joining this PRD unit's `sourceUnits` to `discoveredUnits[].id` and merging their `unitInventory` categories. Deduplicate the merged inventory by item identity (route method/path/owner, test path, export file/name, other entry-point file/name), preserving source evidence. Use this same baseline for generation and verification. #### Step 2: PRD Generation @@ -110,9 +112,10 @@ prompt: | Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged) Related Files: $PRD_UNIT_COMBINED_RELATED_FILES Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS + Unit Inventory: $PRD_UNIT_INVENTORY Use provided scope as investigation starting point. - If tracing entry points reveals files outside this scope, include them. + Inspect dependencies outside these files only when they establish an in-scope behavior or contract; this does not automatically expand feature scope. Create final version PRD based on thorough code investigation. ``` @@ -131,7 +134,7 @@ prompt: | doc_type: prd document_path: $STEP_2_OUTPUT - unit_inventory: [the current unit's Step 1 unitInventory] + unit_inventory: $PRD_UNIT_INVENTORY ``` `unit_inventory` supplies the completeness baseline while repository evidence supplies the search scope. @@ -181,7 +184,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -202,20 +205,22 @@ Each PRD unit from Phase 1 maps to Design Doc unit(s): - **Standard mode (fullstack=No)**: 1 PRD unit → 1 Design Doc (using technical-designer) - **Fullstack mode (fullstack=Yes)**: 1 PRD unit → 2 Design Docs (technical-designer + technical-designer-frontend) -Map `$STEP_1_OUTPUT` units to Design Doc generation targets, carrying forward: +For each PRD unit, join its `sourceUnits` to discovered units and merge their technical evidence and inventory, preserving provenance. Map the result to Design Doc targets, carrying forward: - `technicalProfile.primaryModules` → Primary Files - `technicalProfile.publicInterfaces` → Public Interfaces - `dependencies` → Dependencies - `relatedFiles` → Scope boundary -- `unitInventory` → Unit Inventory (routes, test files, public exports) +- `unitInventory` → Unit Inventory (routes, test files, public exports, other entry points) In fullstack mode, partition each unit inventory by the owning path into backend and frontend target inventories. Assign a shared entry to each Design Doc whose public contract must account for it and record that shared reason; otherwise assign it once. Each Step 7 and Step 8 invocation receives its target's inventory, not the unpartitioned combined unit. +Assign each target a distinct `output_path` before generation. Use `[feature]-design.md` in standard mode and `[feature]-backend-design.md` / `[feature]-frontend-design.md` in fullstack mode. Check existing destinations and preserve unrelated artifacts. + **Store output as**: `$STEP_6_OUTPUT` ### Step 7-10: Per-Unit Processing -**FOR** each unit in `$STEP_6_OUTPUT` **(sequential, one unit at a time)**: +**FOR** each unit in `$STEP_6_OUTPUT`: #### Step 7: Design Doc Generation @@ -238,10 +243,11 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY + output_path: $DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH - Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports should be accounted for in the Design Doc. + Document current architecture as-is. Use Unit Inventory as a completeness baseline — all inventoried capabilities should be accounted for in the Design Doc. ``` **Store output as**: `$STEP_7_OUTPUT` @@ -265,6 +271,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $BACKEND_UNIT_INVENTORY + output_path: $BACKEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH @@ -289,6 +296,7 @@ prompt: | Public Interfaces: $UNIT_PUBLIC_INTERFACES Dependencies: $UNIT_DEPENDENCIES Unit Inventory: $FRONTEND_UNIT_INVENTORY + output_path: $FRONTEND_DESIGN_DOC_OUTPUT_PATH Parent PRD: $APPROVED_PRD_PATH Backend Design Doc: $STEP_7a_OUTPUT @@ -371,7 +379,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, pass code-verifier the same `unit_inventory` plus the previous complete verifier result, dispositions and correction diff or paths as `prior_feedback`. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest `verification_evidence`, `prior_feedback`. #### Unit Completion @@ -394,4 +402,4 @@ Output summary including: |-------|--------| | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | -| Verification is `inconsistent` or inventory remains unaccounted after correction | Flag for mandatory human review — require explicit human approval | +| Required defect remains after Review Resolution | Report the unit incomplete with evidence. A raw verifier label or a resolved decline creates no extra approval gate; optional human review follows Step 0. | diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index 164e91c0..8d8b4390 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -20,7 +20,7 @@ Execute Skill: subagents-orchestration-guide before making workflow decisions, i **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. -**Execution Gate**: Complete Steps 1-10 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. +**Execution Gate**: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result. ## Execution Method @@ -96,7 +96,7 @@ Approve the proposed changes: s) Decline — record the governing reason and accept current state ``` -This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 10. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. @@ -150,41 +150,27 @@ Route the quality-fixer result: - `verification_incomplete` → Retain the complete result and proceed to Step 8 - `blocked` → Apply Specialist Result Acceptance -### Step 8: Re-validate code-reviewer +### Step 8: Reconcile Corrected Findings -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. +Use the shared **Re-run rule** to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original `dev-workflows:code-reviewer` or `dev-workflows:security-reviewer` with the original governing documents, current `implementationFiles`, and `prior_feedback` containing the received finding IDs, dispositions and correction evidence. Derive `implementationFiles` using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract. -Invoke code-reviewer using Agent tool: -- `subagent_type`: "dev-workflows:code-reviewer" -- `description`: "Re-validate implementation review" -- `prompt`: "Re-review the completed implementation after approved corrections. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every received item." - -### Step 9: Re-validate security-reviewer - -Immediately before this invocation, re-derive `implementationFiles` using the Step 1 inclusion rule so it includes implementation artifacts added or changed by the approved corrections. - -Invoke security-reviewer using Agent tool when subagents-orchestration-guide's post-implementation **Re-run rule** requires a current security result: -- `subagent_type`: "dev-workflows:security-reviewer" -- `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. prior_feedback: [{id, disposition, reason?, evidence}]. Reconcile every prior item under the reviewer's re-review scope." - -Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Follow its `maintained` transitions and repeat the affected verification after a rerouted correction; apply the parent requirement or authority gate when Review Resolution exits to it; proceed at its convergence condition. +Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 10, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through Steps 6-9, and report a repeated `verification_incomplete` result. When the retry changes the repository, repeat Steps 8-9 for the changed code before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. -### Step 10: Final Report +### Step 9: Final Report Present the final report: ``` Implementation Review: Initial: [verdict from code-reviewer] - Correction review: [verdict for the re-review scope] (if fixes executed) + Correction review: [verdict for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Security Review: Initial: [status] - Correction review: [status for the re-review scope] (if fixes executed) + Correction review: [status for the re-review scope] (if this reviewer was rerun) Reconciliation: [resolved / withdrawn / maintained by finding ID] Quality Check: diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md index 253af498..defb3cf7 100644 --- a/skills/requirement-convergence/SKILL.md +++ b/skills/requirement-convergence/SKILL.md @@ -1,6 +1,6 @@ --- name: requirement-convergence -description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from decision-relevant repository evidence. Use when a requirement enters a workflow, before design begins. --- # Requirement Convergence @@ -18,7 +18,7 @@ This skill converges **what to build**. How to build it, and which documents the | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | -| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | +| `cost` | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. diff --git a/skills/requirement-convergence/references/criteria.md b/skills/requirement-convergence/references/criteria.md index 9d5cbb91..3e8d0727 100644 --- a/skills/requirement-convergence/references/criteria.md +++ b/skills/requirement-convergence/references/criteria.md @@ -29,20 +29,9 @@ An adjacent capability the agent noticed stays out of both `requirements[]` and ## cost -Cost follows structure and count, not behavior, so it is decided from these inputs alone: +Estimate rough lifecycle cost from affected responsibilities, contract consumers, reusable behavior, state/migration needs and existing verification support. Inspect enough representative behavior to decide whether an apparent reuse or structural match actually serves the requirement. Use analyzer evidence when supplied. Stop before implementation-level investigation once further detail cannot change scope, cost band or the user decision. -| Input | How it is obtained | -|-------|--------------------| -| Number and kind of targets to change | Grep/Glob over the affected files | -| Number of boundaries crossed | Affected path composition plus import and caller tracing | -| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | -| Whether persisted state needs converting | Whether a schema or migration path is in the change set | -| Whether verification support already exists | Glob for the area's existing test harness | -| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | - -Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. - -Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. +Record `cost` as one evidence-supported band and its remaining unknowns. When an unresolved condition could raise the band, state that condition and the higher-band consequence in the existing cost evidence so scope confirmation exposes the trade-off. A flow declares `cost` out of scope only where its own steps say so. ## Challenge intensity @@ -51,10 +40,10 @@ The band's only job is to select a row here, so cheap requirements stay cheap to | Band | Meaning | Challenge | |------|---------|-----------| | `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | -| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | -| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | +| `medium` | Reverting would touch other work | Present cost and a lower-cost alternative when a materially distinct sufficient option exists | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off; obtain a user decision when a required outcome, explicit constraint or irreversible-action authority must change | -Report an unknown that would move the band up as a blocking question rather than assuming the lower band. +Resolve repository-answerable uncertainty locally. Ask the user only when a remaining unknown changes required scope, constraints or authority; otherwise record its cost effect and keep independent work moving. ## Solution-in-disguise test diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 555c3632..3303e4f7 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -156,7 +156,7 @@ Rules: - When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` - When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported - Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add only their named UI or layer artifact paths +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -204,7 +204,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. + +When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -244,7 +246,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - - Otherwise → Proceed to step 3 + - Implementation is complete with supporting repository evidence → Proceed to step 3 + - Otherwise → Apply Specialist Result Acceptance 3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance @@ -282,7 +285,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-03b: applied design-evidence finding → technical-designer - Invoke the owning designer as a fresh `update` call with the existing Design Doc path and complete `correction_findings` objects copied verbatim with only their `apply` dispositions added. - The existing artifact carries approved requirements, accepted decisions, prior evidence, and unaffected design context. Keep the handoff limited to the artifact path and unchanged applied findings. -- The designer applies its review-triggered self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. +- The designer applies its review-triggered bounded self-verification gate, updates the artifact or returns the exact unresolved premise, and the orchestrator reruns the originating verifier or reviewer. ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. @@ -302,8 +305,8 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner - Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. -- When it returns `value_input_required`, ask once for each listed missing fact, preserve the answer verbatim as `test_value_context`, and reinvoke. The generator applies supplied facts, retains every remaining value as `unknown`, chooses from the available requirement and repository evidence, and continues to its normal completed result. -- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, confirm from the Design Doc that no accepted proof obligation requires that boundary, and return an uncovered obligation to the generator for completion. +- Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. +- Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. - Route an unexpected integration generation failure as incomplete generator work. A validated null E2E lane is complete. diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 289f8bf3..2967d10c 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -77,7 +77,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. - Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per owning-designer invocation serially, and repeats the complete batch review; `rejected` resolves the governing-source conflict before another review. -- Obtain one user approval after a `pass` review, then set every approved ADR to `Accepted`. +- Obtain one user approval after Review Resolution converges and governing-source conflicts are resolved, then set every approved ADR to `Accepted`. - An empty batch proceeds directly to both Design Docs. ## Layer Design Context @@ -88,6 +88,7 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-backend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -98,6 +99,7 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc +output_path: docs/design/[feature-name]-frontend-design.md confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] structural_scale: [confirmed scale] adr_paths: [accepted paths or []] @@ -117,7 +119,7 @@ After both document reviews permit approval, invoke design-sync with `source_des ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for `value_input_required` and its unknown-value continuation before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md index 8da4072d..078058c3 100644 --- a/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -19,7 +19,7 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. For code-verifier with `unit_inventory`, its full current-document inventory accounting still applies. A decline-only result is complete. ## 1. Assess Every Finding @@ -58,9 +58,9 @@ Select the existing correction owner from the accepted state each finding requir For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. -For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. +For an applied Design Doc finding about an unverified decision-changing premise, the fresh technical-designer invocation applies its review-triggered bounded self-verification gate. The finding carries the exact premise and required evidence; the designer selects existing evidence, a smaller design valid under every unresolved outcome, or a probe when all gate conditions hold. Rerun the originating verifier or reviewer after the update. -For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. +For a reconciliation reviewer, reuse the initial reviewer inputs and add `prior_feedback` as an array of `{ id, disposition, reason?, evidence }`. For each ID, preserve the original finding claim and basis verbatim in `evidence`, alongside the correction diff or paths. The correction assessment covers exactly every received item. The reviewer completes that scope and then: @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/skills/testing-principles/SKILL.md b/skills/testing-principles/SKILL.md index df9c948f..72579f85 100644 --- a/skills/testing-principles/SKILL.md +++ b/skills/testing-principles/SKILL.md @@ -11,6 +11,7 @@ Tests here guarantee accepted behavior, and the next agent reads every existing - Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules. - Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere. +- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary. - Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself. - Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it.