quality-commitments

Files (32)

• SKILL.md
• clippy.toml · stacks/cli-rust/
• definition-of-done.md · stacks/cli-rust/
• github-workflows-ci.yml · stacks/cli-rust/
• matrix.md · stacks/cli-rust/
• notes.md · stacks/cli-rust/
• pr-template.md · stacks/cli-rust/
• definition-of-done.md · stacks/data-pipeline-python/
• github-workflows-ci.yml · stacks/data-pipeline-python/
• matrix.md · stacks/data-pipeline-python/
• notes.md · stacks/data-pipeline-python/
• pr-template.md · stacks/data-pipeline-python/
• pyproject-snippet.toml · stacks/data-pipeline-python/
• notes.md · stacks/fullstack/
• definition-of-done.md · stacks/mobile-rn/
• github-workflows-ci.yml · stacks/mobile-rn/
• matrix.md · stacks/mobile-rn/
• notes.md · stacks/mobile-rn/
• pr-template.md · stacks/mobile-rn/
• definition-of-done.md · stacks/rest-api-node/
• eslint.config.js · stacks/rest-api-node/
• github-workflows-ci.yml · stacks/rest-api-node/
• matrix.md · stacks/rest-api-node/
• notes.md · stacks/rest-api-node/
• pr-template.md · stacks/rest-api-node/
• definition-of-done.md · stacks/web-react/
• eslint.config.js · stacks/web-react/
• github-workflows-ci.yml · stacks/web-react/
• matrix.md · stacks/web-react/
• notes.md · stacks/web-react/
• playwright.config.ts · stacks/web-react/
• pr-template.md · stacks/web-react/

SKILL.md (first lines)

You are facilitating **Quality Commitments** work. The core principle: **a team owns their definition of quality.** Standards are not imposed — they are collaboratively defined with stakeholders, made operational through tooling and CI, and continuously refined through learning.

## Preconditions (read these before doing anything)

Every mode below assumes the team is operating under these non-negotiables. Surface them explicitly if a session feels off-track.

1. **Team ownership.** The team — not management, not a separate QA org — defines, maintains, and revises its quality commitments collaboratively with stakeholders.
2. **Blame-free posture.** Defects are systemic learning opportunities, not career events. If a session starts hunting for individuals to blame, pause and reset.
3. **QA as exploratory expert.** QA professionals are a critical line of defense providing exploratory, boundary-pushing, and expert testing value. They are not scripted-regression machines. Integrate them as part of the broader team, not siloed.
4. **Shared language.** The Quality Commitments Matrix exists to prevent confusion about what "tested" actually means. When in doubt, write it down in the matrix.

## When NOT to use this skill

- Single-file bugfixes, hotfixes, or one-off patches — invoke `systematic-debugging` instead
- Drive-by refactors with no kickoff or retrospective need
- Tasks where the user wants implementation help, not a quality conversation

Use this skill when the work is **kickoff, audit, scaffold, or retrospective** in nature.

## Modes

Ask the user which mode they want. Cross-links between modes are noted — chain them when it helps.

1. **Workshop** — collaboratively define what quality means for this project → typically followed by **Matrix**
2. **Matrix** — generate or update the Quality Commitments Matrix → typically follows Workshop or Scan
3. **Scan** — evidence-based audit of an existing repo → typically followed by Workshop (close gaps) or Scaffold (fill missing tooling)
4. **Scaffold** — apply a stack template to a target repo, writing real CI/lint/test/DoD files
5. **Triage** — classify a defect (commitment failure vs. gap) and produce a learning summary → may update the Matrix
6. **Templates** — browse stack starter content without committing to Scan or Scaffold

---

## Mode 1 — Workshop

Facilitate a Sprint-Zero quality definition session.

### Step 1 — Establish context
Ask:
- What system/product is being built or maintained?
- Who are the key stakeholders (product, engineering, QA, customers, ops)?
- Is this greenfield, legacy, or a significant feature addition?
- Which stack template fits? *(REST API / Microservice — Node, Web App — React, Data Pipeline — Python, CLI — Rust, Mobile — React Native, Full-stack, or "scratch" to build from nothing)*

If a template is chosen, present its prioritized attributes from **Mode 6 Templates** as a starting point, then jump to Step 3.

### Step 2 — Quality attribute selection (skip if a template was chosen)
Walk through these categories. For each one the team selects, ask: *What does "good enough" look like for this project?*

- **Functional:** correctness, completeness, compliance
- **Reliability:** availability, fault tolerance, recoverability, maturity
- **Performance:** response time, throughput, resource efficiency, scalability
- **Security:** confidentiality, integrity, authenticity, non-repudiation
- **Maintainability:** modularity, reusability, analyzability, modifiability, testability
- **Usability:** learnability, operability, accessibility, user error protection
- **Portability:** adaptability, installability, replaceability
- **Compatibility:** co-existence, interoperability

### Step 3 — Ownership conversation
For each selected attribute, surface:
- Who is responsible for measuring it?
- How will it be verified (automated, manual, exploratory)? Name the QA contribution explicitly — exploratory testing is a distinct, valuable column, not a fallback for "we didn't automate it."
- What is the Definition of Done entry for this attribute?

### Step 4 — Output
Produce a markdown summary: agreed attributes, owners, DoD entries. Offer to continue into **Mode 2 (Matrix)** to formalize these as commitments.

---

## Mode 2 — Quality Commitments Matrix

Before generating, ask: *"Start from a stack template, or blank?"* If a template is chosen, read its `matrix.md` from `stacks/<stack>/matrix.md` (relative to this skill's directory) and present it.

The matrix documents how the team ensures quality across every testing type they commit to. Columns:

| Quality Type | Phase | In Definition of Done? | Runs on CI? | Covers Regressions? | Documents Findings? | Boundary Coverage | Perspective |
|---|---|---|---|---|---|---|---|

**Column guidance:**

- **Quality Type:** unit tests, integration tests, contract tests, linting, code coverage, BDD/acceptance, performance, security scanning, accessibility, exploratory, manual UAT, observability/alerting, etc.
- **Phase:** Development, PR review, Merge, UAT, Release
- **In Definition of Done?** Yes / No / Partial
- **Runs on CI?** Yes / No / Manual trigger
- **Covers Regressions?** Yes / No / Partial
- **Documents Findings?** Yes / No / Partial — does this practice produce a written artifact (test report, audit log, scan output, retro note) that the team revisits?
- **Boundary Coverage:** Positive cases, Negative cases, Property-based, Edge cases
- **Perspective:** White box (internal), Black box (external), Grey box

After generating the matrix, ask:
- Are there gaps — quality types the team cares about but hasn't committed to yet?
- Any rows where **Runs on CI?** is "No" that should be automated?
- Any rows where **Documents Findings?** is "No" — quietly running tools whose output nobody reads?

Offer to continue into **Mode 4 (Scaffold)** to write the tooling, or **Mode 3 (Scan)** to compare against what is actually in the repo today.

---

## Mode 3 — Scan (evidence-based repo audit)

Inspect an existing repository and produce a Quality Commitments Matrix reflecting **what is actually present**, not what the team wishes were present. Gaps are called out explicitly.

### Step 1 — Identify project type
Ask: *"Which stack does this repo most resemble? (REST API/Microservice, Web App, Data Pipeline, CLI, Mobile, Full-stack, or Other)"* — used as the gap baseline. Infer from findings if unsure.

### Step 2 — Discover

Work through every category. Record evidence (file paths) for what you find.

**2a. Project structure & language** — read `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `*.csproj`, `Gemfile`. Identify primary language(s), framework(s), and test directory naming convention.

**2b. Unit & integration tests** — `jest.config.*`, `pytest.ini`, `vitest.config.*`, `mocha.*`, `phpunit.xml`, `rspec` in Gemfile, `xunit.*`. Sample test files to infer unit vs. integration style. Coverage config: `.nycrc`, `codecov.yml`, `jacoco`, `coverageThreshold`.

**2c. Linting & static analysis** — `.eslintrc*`, `eslint.config.*`, `.rubocop.yml`, `pylintrc`, `.flake8`, `mypy.ini`, `pyproject.toml [tool.ruff]`, `.golangci.yml`, `clippy.toml`, `sonar-project.properties`, `biome.json`, `.stylelintrc*`.

**2d. CI/CD** — `.github/workflows/*.yml`, `.circleci/config.yml`, `.gitlab-ci.yml`, `Jenkinsfile`, `Makefile` test/lint targets, `.travis.yml`, `azure-pipelines.yml`, `buildkite.yml`. For each, record jobs, triggers, and which checks they include.

**2e. Security scanning** — workflow files referencing `trivy`, `snyk`, `semgrep`, `codeql`, `dependabot`, `gitleaks`, `checkov`, `bandit`, `brakeman`, `gosec`. Also `.snyk`, `semgrep.yml`, `.gitleaks.toml`, `dependabot.yml`.

**2f. Contract & API testing** — `pact/`, `*.pact.json`, OpenAPI/Swagger specs, Postman collections, REST-assured/Karate/Dredd references.

From folkengine/.claude, Apache-2.0.

More from folkengine/.claude