quality-gardening

Quality Gardening

Overview

Track quality as concrete metrics and debt movement, not as a vague single score.

This skill freezes new degradation first, then uses generated metrics to show current quality and convergence direction. For shared harness terms, see ../../references/harness-patterns.md; when quality surfaces are absent, use references/build-when-missing.md. For generated snapshot ownership, see references/generated-snapshot-ownership.md.

When To Use

• The user asks to design, evaluate, or maintain QUALITY_SCORE.md, quality reports, quality snapshots, debt reduction, or red lines.
• A repository needs structural metrics beyond lint and tests.
• The team needs periodic gardening instead of a one-time large refactor.

Inputs Needed

• Current quality pain points: large files, scattered events, direct API calls, duplicated entrypoints, missing tests, or similar risks.
• Source paths to scan and paths to exclude.
• CI or scheduled run strategy.

Execution Order

• First: Find existing quality docs, generated reports, lint checks, and baselines.
• Then: Choose a small set of trackable metrics and thresholds; do not create a fake aggregate score.
• Finally: Output the quality report shape, gate policy, and convergence cadence.

Step-by-Step Process

1. Search for QUALITY_SCORE.md, quality scripts, baselines, and CI gardening workflows.
2. Choose four to eight metrics, and make each one automatically collectable.
3. If no quality report exists, bootstrap the minimum score/report/baseline set from references/build-when-missing.md.
4. Separate blocking gates from informational reports.
5. Use thresholds or baselines for historical problems; new degradation should fail.
6. Generate Markdown for humans and JSON for scripts and trends.
7. Design a gardening cadence: lower one threshold or close one allowlist item at a time.

Checks

• Metrics: each metric is repeatable and reflects a real structural risk.
• Thresholds: checks freeze new degradation instead of demanding immediate full cleanup.
• Reports: each finding includes path, metric, current value, threshold, and suggested action.
• CI: it is clear which metrics fail builds and which only report.
• Incentives: do not hide critical risks behind one attractive total score.

Output Format

# Quality Gardening

## Detected Mapping
- quality:
- validation:
- work-state:

## Metrics
| Metric | Source | Threshold | Gate |
| --- | --- | --- | --- |

## Generated Reports
-

## Baseline Policy
-

## Garden Loop
-

## Non-Goals
-

Common Mistakes

• Inventing a good-looking total score that does not guide repairs.
• Tracking too many metrics, so nobody reads or fixes them.
• Skipping baselines, which makes the quality gate unusable on day one.
• Treating one large refactor as quality governance.

Example Prompts

• "Design QUALITY_SCORE.md and a quality report for this repo."
• "How should we track structural debt without inventing a fake score?"
• "Add historical large files and scattered calls to a quality garden."