I Validate User Story Completion
Published by ecarrenolozano in ai-sdlc-skills
What this skill does
Validate implemented user stories against approved acceptance criteria with BDD, Gherkin feature files, and pytest-bdd. Use after g-implement-repository-work when one or more implemented stories need completion evidence before pull request creation, when tests/validation scenarios must be created or run, or when sdlc_docs/trace_workflow.md must record user-story validation status. Do not use for initial implementation TDD, requirements authoring, architecture design, release deployment, or pull
Add I Validate User Story Completion to your agent
Review the source and files first. When you are ready, copy the prompt instruction or use the CLI command supported by your environment.
Install with a prompt
Paste this into a compatible coding agent:
add this skill "i-validate-user-story-completion" from https://github.com/ecarrenolozano/ai-sdlc-skillsInstall with the CLI
Run this command in a controlled environment after reviewing the repository:
npx skills add https://github.com/ecarrenolozano/ai-sdlc-skills --skill i-validate-user-story-completionSkill instructions
User Story Completion Validation
Purpose
Confirm that implemented user stories satisfy approved acceptance criteria through executable BDD scenarios. Treat approved Product Requirements, implementation evidence, existing tests, and workflow traceability as inputs. Produce validation evidence, not new product scope.
Governing Rules
- Work in English.
- Use the exact skill identifier
i-validate-user-story-completion. - Treat
sdlc_docs/trace_workflow.mdas the canonical workflow status file when present. - Verify Product Requirements are approved and the selected user stories have implementation evidence before creating validation scenarios.
- Use Gherkin feature files under
tests/validation/features/. - Use pytest-bdd step definitions under
tests/validation/steps/. - Map every selected acceptance criterion to at least one scenario or record why it cannot yet be validated.
- Preserve acceptance-criterion meaning. Do not add product behavior, validation rules, error handling, roles, data, or workflows not approved upstream.
- Preserve prior BDD scenario mappings and validation evidence for stories later marked
SupersededorRetired. Add or update validation for the new active story IDs instead of overwriting historical evidence, unless a human explicitly approves archival cleanup. - Keep BDD validation separate from implementation TDD. Route missing implementation behavior to
g-implement-repository-work. - Use
pytestandpytest-bdd; do not introduceunittest.TestCase. - Require explicit approval of the visible validation proposal before local writes.
- Re-read affected files and
trace_workflow.mdimmediately before writing. - Do not commit, push, create pull requests, close issues, move project items, or publish comments without separate approval.
- Never claim validation passed unless the command was executed successfully.
Canonical Inputs
Read the applicable project-owned artifacts when present:
sdlc_docs/01_requirements/product_requirements.md
sdlc_docs/02_architecture/architecture.md
sdlc_docs/02_architecture/code-level.md
sdlc_docs/03_implementation/backlog_priority.md
sdlc_docs/trace_workflow.md
tests/README.md
tests/validation/
pyproject.toml or equivalent test configuration
Use implementation evidence from local status tracking, changed files, commits, or the selected issue. Do not hardcode any project-specific paths beyond the generic SDLC and pytest-bdd conventions above.
Traceability Ownership
The skill owns the User story validation row in sdlc_docs/trace_workflow.md.
Controlled overlap with Implementation is allowed when both rows are In Progress and validation work is limited to implemented story subsets with explicit evidence.
Allowed fields on the owned row:
Status
Current activity
Evidence
Missing or blocked
Next action
The skill may update only handoff fields in an Implementation row after validation passes, and only when that row exists and the workflow explicitly uses it. It must not modify requirements, architecture, repository preparation, foundation, pull request, release, or unrelated increment rows.
Use these row patterns when a project template has no stronger local convention:
| User story validation | Initial Release | Not Started | BDD User Story Completion Validation | implemented stories available | BDD validation has not run | Run i-validate-user-story-completion |
| User story validation | Initial Release | In Progress | BDD User Story Completion Validation | selected implemented stories and approved requirements; subset scope and commands recorded | BDD mapping or validation execution pending for remaining stories | Continue i-validate-user-story-completion |
| User story validation | Initial Release | Blocked | BDD User Story Completion Validation | attempted BDD validation | implementation evidence, acceptance criteria, or scenario execution blocked | Resolve blocker with i-validate-user-story-completion or route upstream |
| User story validation | Initial Release | Complete | BDD User Story Completion Validation | passing `tests/validation` command and story-scenario mapping | None | Run h-create-implementation-pull-request |
Before every traceability write:
- copy the current trace file to a temporary location outside the repository;
- prepare the proposed after-file;
- validate only authorized row and field changes;
- reject unauthorized changes and preserve the original file;
- report changed fields and unauthorized-change count.
Use scripts/validate_bdd_validation.py for objective checks. Do not replace a missing validator with manual confidence.
Workflow
- Locate the repository root.
- Identify the selected implemented story or stories.
- Read approved Product Requirements and acceptance criteria for the selected scope.
- Read implementation evidence and existing validation tests.
- Verify pytest-bdd configuration and
tests/validation/features/plustests/validation/steps/. - Read
references/bdd-validation-policy.md. - Create the acceptance-criterion to scenario mapping.
- Identify missing information, unsupported behavior, or implementation gaps.
- If blocking information is missing, update the validation row to
BlockedorUnder Clarification, report the blocker, and stop. - Present the validation proposal: selected stories, criteria, scenario names, feature files, step files, commands, trace updates, and out-of-scope work.
- Stop for explicit approval before local writes.
- Re-read affected files and traceability after approval.
- Create or update Gherkin feature files.
- Create or update pytest-bdd step definitions.
- Run targeted validation scenarios.
- Run the full validation command for the selected scope or
tests/validation. - Run
scripts/validate_bdd_validation.py. - If validation fails because implementation is incomplete, record the failing scenario and route to
g-implement-repository-work. - If validation fails because acceptance criteria are unclear, route to
c-manage-product-requirements. - If validation passes, update authorized traceability fields and set next action to
Run h-create-implementation-pull-request. - Report scenario coverage, command results, files changed, trace fields changed, and remaining gaps.
During overlap with ongoing implementation, keep User story validation as In Progress for subset evidence and do not claim full-stage completion until selected completion gates are met.
Completion Gates
Validation is complete only when:
- every selected approved acceptance criterion is mapped to a scenario or explicitly blocked;
- every mapped scenario is implemented as Gherkin and pytest-bdd steps;
- validation tests pass for the selected scope;
- BDD evidence names the exact commands and results;
- traceability is updated only through authorized fields;
- no product behavior, requirements, architecture, or foundation decision was invented;
- downstream action is
Run h-create-implementation-pull-requestonly after validation passed.
Resources
- Read
references/bdd-validation-policy.mdbefore mapping scenarios. - Read
references/golden-example/browser-task-board/README.mdwhen a concrete progressive example is useful. - Run
scripts/validate_bdd_validation.pyafter creating or updating validation scenarios.
Progressive Audit Resources
- Read
references/golden-example/README.mdonly when a progressive concrete example is useful. - Read
references/process_flowchart.mdonly for human explanation or audit.
Files included
- agents/openai.yaml
- references/bdd-validation-policy.md
- references/golden-example/browser-task-board/bdd-mapping.md
- references/golden-example/browser-task-board/in-repository/pyproject.toml
- references/golden-example/browser-task-board/in-repository/sdlc_docs/trace_workflow.md
- references/golden-example/browser-task-board/in-repository/tests/README.md
- references/golden-example/browser-task-board/in-trace_workflow.md
- references/golden-example/browser-task-board/out-repository/pyproject.toml
- references/golden-example/browser-task-board/out-repository/sdlc_docs/trace_workflow.md
- references/golden-example/browser-task-board/out-repository/tests/validation/features/create_task.feature
- references/golden-example/browser-task-board/out-repository/tests/validation/steps/test_create_task_steps.py
- references/golden-example/browser-task-board/out-trace_workflow.md
- references/golden-example/browser-task-board/proposal.md
- references/golden-example/browser-task-board/README.md
- references/golden-example/browser-task-board/result.md
- references/golden-example/browser-task-board/selected-implemented-story.md
- references/golden-example/browser-task-board/validation-execution.md
- references/golden-example/README.md
- references/process_flowchart.md
- scripts/validate_bdd_validation.py
- SKILL.md

