--- name: gate-check type: workflow description: "Validates a software product, service, or feature against readiness gates before advancing to the next delivery phase. Use when planning a phase transition or when the user mentions gate check, phase review, or readiness validation." argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write effort: 3 when_to_use: "When validating software delivery readiness to advance to the next development phase" --- # Phase Gate Validation This skill validates whether the software project is ready to advance to the next delivery phase. It checks for required artifacts, quality standards, and operational blockers. **Distinct from `/project-stage-detect`**: That skill is diagnostic ("where are we?"). This skill is prescriptive ("are we ready to advance?" with a formal verdict). ## Production Stages (7) The project progresses through these stages: 1. **Concept** - Problem framing, product concept document 2. **Systems Design** - Requirements, workflows, architecture boundaries 3. **Technical Setup** - Stack selection, CI/CD, environments, architecture decisions 4. **Pre-Production** - Spikes, prototypes, acceptance criteria, delivery planning 5. **Production** - Feature development and integration work 6. **Polish** - Stabilization, QA hardening, performance, operational readiness 7. **Release** - Go-live prep, support readiness, rollback and communication planning **When a gate passes**, write the new stage name to `production/stage.txt` (single line, e.g. `Production`). This updates the status line immediately. --- ## 1. Parse Arguments - **With argument**: `/gate-check production` - validate readiness for that specific phase - **No argument**: Auto-detect current stage using the same heuristics as `/project-stage-detect`, then validate the NEXT phase transition --- ## 2. Phase Gate Definitions ### Gate: Concept -> Systems Design **Required Artifacts:** - [ ] `design/docs/product-concept.md` exists and has content - [ ] Product pillars defined (in concept doc or `design/docs/product-pillars.md`) - [ ] Success metrics or launch goals captured in the concept or PRD seed notes **Quality Checks:** - [ ] Product concept has been reviewed (`/design-review` verdict not MAJOR REVISION NEEDED) - [ ] Primary user workflow or business outcome is described and understood - [ ] Target audience and problem statement are identified --- ### Gate: Systems Design -> Technical Setup **Required Artifacts:** - [ ] Systems index exists at `design/docs/systems-index.md` with at least MVP systems enumerated - [ ] At least 1 PRD in `design/docs/` (beyond product-concept.md and systems-index.md) **Quality Checks:** - [ ] PRD(s) pass design review (8 required sections present) - [ ] System dependencies are mapped in the systems index - [ ] MVP priority tier is defined - [ ] Non-functional requirements are captured where relevant (performance, security, reliability, compliance) --- ### Gate: Technical Setup -> Pre-Production **Required Artifacts:** - [ ] Stack chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`) - [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated) - [ ] At least 1 Architecture Decision Record in `docs/architecture/` - [ ] CI/CD workflow, build script, or release automation exists - [ ] Environment strategy documented (dev/staging/prod, secrets handling, deployment path) **Quality Checks:** - [ ] Architecture decisions cover core domains, data flow, integrations, and deployment concerns - [ ] Technical preferences have naming conventions and performance budgets set - [ ] Operational ownership is clear for build, deploy, and rollback paths --- ### Gate: Pre-Production -> Production **Required Artifacts:** - [ ] At least 1 prototype, spike, or technical validation artifact exists with notes or a README - [ ] First sprint plan exists in `production/sprints/` - [ ] All MVP-tier PRDs from systems index are complete - [ ] Initial delivery scope is defined for the first release or milestone **Quality Checks:** - [ ] Prototype or spike validates the riskiest technical assumption or critical user workflow - [ ] Sprint plan references real work items from PRDs - [ ] Acceptance criteria and release scope are defined - [ ] Dependencies and sequencing risks are identified --- ### Gate: Production -> Polish **Required Artifacts:** - [ ] `src/` has active code organized into subsystems - [ ] All core workflows from PRD are implemented (cross-reference `design/docs/` with `src/`) - [ ] Main user journey works end-to-end in a dev or staging environment - [ ] Test files exist in `tests/` - [ ] Deployment or release scripts exist - [ ] QA/UAT evidence exists (test summary, checklist, sign-off notes, or release candidate results) **Quality Checks:** - [ ] Tests are passing (run test suite via `Bash`) - [ ] No critical/blocker bugs in any bug tracker or known issues - [ ] Critical acceptance criteria are satisfied (compare to PRD acceptance criteria) - [ ] Performance and reliability are within target budgets (check technical-preferences.md targets) - [ ] Logs, metrics, and error reporting exist for critical paths --- ### Gate: Polish -> Release **Required Artifacts:** - [ ] All features from the milestone plan are implemented or explicitly deferred - [ ] Environment variables, secrets, and feature flags are audited for release - [ ] Localization strings are externalized (no hardcoded user-facing text in `src/`) - [ ] QA test plan exists - [ ] Release checklist completed (`/release-checklist` or `/launch-checklist` run) - [ ] Deployment and rollback runbook exists - [ ] Customer-facing release artifacts are prepared (release notes, support notes, status-page/internal comms as applicable) - [ ] Changelog / patch notes drafted **Quality Checks:** - [ ] Full QA or UAT pass signed off by the owning team - [ ] All automated checks and release validations are passing - [ ] Performance, availability, and operational targets are met for the release surface - [ ] No known critical or high-severity bugs; medium-severity items have documented accepted risk - [ ] Accessibility basics covered for the release surface - [ ] Localization verified for all target languages - [ ] Legal, privacy, and security requirements are met (privacy policy, consent, licenses, terms as applicable) - [ ] Production deployment, packaging, or publish flow completes cleanly - [ ] Monitoring, alerting, and incident communication paths are ready --- ## 3. Run the Gate Check For each item in the target gate: ### Artifact Checks - Use `Glob` and `Read` to verify files exist and have meaningful content - Don't just check existence - verify the file has real content (not just a template header) - For code checks, verify directory structure and file counts ### Quality Checks - For test checks: Run the test suite via `Bash` if a test runner is configured - For design review checks: `Read` the PRD and check for the 8 required sections - For performance checks: `Read` technical-preferences.md and compare against any profiling data in `tests/performance/` or recent `/perf-profile` output - For localization checks: `Grep` for hardcoded strings in `src/` - For release readiness checks: `Read` runbooks, release notes, deployment docs, and QA summaries if they exist ### Cross-Reference Checks - Compare `design/docs/` documents against `src/` implementations - Check that every system referenced in architecture docs has corresponding code - Verify sprint plans reference real work items - Verify deployment, environment, and rollback expectations are reflected in documentation or automation --- ## 4. Collaborative Assessment For items that can't be automatically verified, **ask the user**: - "I can't automatically verify business or QA sign-off. Has the release candidate been approved?" - "No regression summary was found. Has QA or UAT completed a full pass?" - "Performance or reliability evidence isn't available. Would you like to run `/perf-profile` or review recent monitoring data?" **Never assume PASS for unverifiable items.** Mark them as MANUAL CHECK NEEDED. --- ## 5. Output the Verdict ```markdown ## Gate Check: [Current Phase] -> [Target Phase] **Date**: [date] **Checked by**: gate-check skill ### Required Artifacts: [X/Y present] - [x] design/docs/product-concept.md - exists, 2.4KB - [ ] docs/architecture/ - MISSING (no ADRs found) - [x] production/sprints/ - exists, 1 sprint plan ### Quality Checks: [X/Y passing] - [x] PRD has 8/8 required sections - [ ] Tests - FAILED (3 failures in tests/unit/) - [?] QA sign-off - MANUAL CHECK NEEDED ### Blockers 1. **No Architecture Decision Records** - Create an ADR before entering production. 2. **3 test failures** - Fix failing tests in tests/unit/ before advancing. ### Recommendations - [Priority actions to resolve blockers] - [Optional improvements that aren't blocking] ### Verdict: [PASS / CONCERNS / FAIL] - **PASS**: All required artifacts present, all quality checks passing - **CONCERNS**: Minor gaps exist but can be addressed during the next phase - **FAIL**: Critical blockers must be resolved before advancing ``` --- ## 6. Update Stage on PASS When the verdict is **PASS** and the user confirms they want to advance: 1. Write the new stage name to `production/stage.txt` (single line, no trailing newline) 2. This immediately updates the status line for all future sessions **Always ask before writing**: "Gate passed. May I update `production/stage.txt` to 'Production'?" --- ## Protocol - **Question**: Asks about unverifiable quality checks (QA/UAT sign-off, monitoring evidence, manual validation) - **Options**: Skip - gate is auto-detected or specified by argument - **Decision**: User confirms whether to advance on PASS verdict - **Draft**: Full gate check report shown in conversation before updating stage - **Approval**: "May I update `production/stage.txt` to '[new-stage]'?" - only on PASS + user confirmation ## Output Deliver exactly: - **Gate being checked**: `[Current Phase] -> [Target Phase]` - **Artifacts**: X/Y present (with list of missing items) - **Quality checks**: X/Y passing (with list of failures and MANUAL CHECK NEEDED items) - **Blockers**: numbered list, or "None" - **Verdict**: `PASS` / `CONCERNS` / `FAIL` --- ## 7. Follow-Up Actions Based on the verdict, suggest specific next steps: - **No product concept?** -> `/brainstorm` to create one - **No systems index?** -> `/map-systems` to decompose the concept into systems - **Missing design docs?** -> `/reverse-document` - **Missing ADRs?** -> `/architecture-decision-records` - **Tests failing?** -> `/test-driven-development` - **No QA or release evidence?** -> `/release-checklist` or `/launch-checklist` - **Performance unknown?** -> `/perf-profile` - **Security or compliance gaps?** -> `/security-audit` - **Not localized?** -> `/localize` - **Ready for release?** -> `/launch-checklist` --- ## Collaborative Protocol This skill follows the collaborative design principle: 1. **Scan first**: Check all artifacts and quality gates 2. **Ask about unknowns**: Don't assume PASS for things you can't verify 3. **Present findings**: Show the full checklist with status 4. **User decides**: The verdict is a recommendation - the user makes the final call 5. **Get approval**: "May I write this gate check report to production/gate-checks/?" **Never** block a user from advancing - the verdict is advisory. Document the risks and let the user decide whether to proceed despite concerns.