Golden Principles Cleanup

Golden Principles Cleanup Skill

Overview

The golden-principles-cleanup skill reads your project's golden rules from .claude/principles.yaml, scans the entire codebase for violations (using the harness principles gate or a text-based fallback), and emits one cleanup task definition per violation cluster into docs/exec-plans/cleanup-tasks.yaml.

Each task carries the full context an agent needs to open and complete a focused refactoring PR:

• scope — the list of affected files
• description — what to change and why, including affected line numbers and concrete refactoring steps
• pr_title — a conventional-commit-formatted PR title
• pr_body — a complete PR description with What & Why, Changes, and a testing checklist

This skill is read-only for source files. It never modifies application code — it only generates the task manifest.

Workflow

.claude/principles.yaml
        │
        ▼
 [Step 0] Load principles
        │
        ▼
 [Step 1] Run harness evaluate --gate principles --format json
        │  (falls back to text-based grep scan if harness unavailable)
        ▼
 [Step 2] Group GateFailure items by principle_id
        │
        ▼
 [Step 3] Generate CleanupTask per violation cluster
        │
        ▼
 [Step 4] Write docs/exec-plans/cleanup-tasks.yaml
        │
        ▼
 [Step 5] Publish summary to shared-state.yaml  (optional)
        │
        ▼
 [Step 6] Print summary table

Quick decision guide:

• Want to see what tasks would be generated without writing a file? → Use --dry-run
• Only care about must-fix violations? → Use --only-blocking
• Already generated tasks and want to review them? → Use the list subcommand

CLI Usage

Generate cleanup tasks

# Generate all tasks (harness gate + fallback)
python skills/golden_principles_cleanup.py generate

# Only blocking-severity violations
python skills/golden_principles_cleanup.py generate --only-blocking

# Preview without writing the file
python skills/golden_principles_cleanup.py generate --dry-run

# Custom principles file and output path
python skills/golden_principles_cleanup.py generate \
    --principles-file path/to/principles.yaml \
    --output path/to/cleanup-tasks.yaml

# Generate without publishing to shared-state
python skills/golden_principles_cleanup.py generate --no-publish

List generated tasks

# Print a summary table of the generated cleanup-tasks.yaml
python skills/golden_principles_cleanup.py list

# List from a custom output path
python skills/golden_principles_cleanup.py list \
    --output path/to/cleanup-tasks.yaml

Programmatic Usage

Generate a manifest

from pathlib import Path
from skills.golden_principles_cleanup import GoldenPrinciplesCleanup

cleanup = GoldenPrinciplesCleanup()

manifest = cleanup.generate_all(
    principles_file=Path(".claude/principles.yaml"),
    output_file=Path("docs/exec-plans/cleanup-tasks.yaml"),
   
    dry_run=False,
)

print(f"Generated {manifest.task_count} task(s)")
for task in manifest.tasks:
    print(f"  {task.id}  [{task.severity}]  {task.pr_title}")

Inspect individual tasks

from skills.golden_principles_cleanup import GoldenPrinciplesCleanup, CleanupTask

cleanup = GoldenPrinciplesCleanup()
principles = cleanup.load_principles(Path(".claude/principles.yaml"))
violations = cleanup.run_principles_gate()

if not violations:
    violations = cleanup.fallback_scan(principles)

grouped = cleanup.group_violations(violations, principles)

for principle_id, viols in grouped.items():
    principle = next(p for p in principles if p["id"] == principle_id)
    task: CleanupTask = cleanup.generate_task(principle, viols)
    print(task.model_dump_json(indent=2))

Publish to shared-state

from skills.golden_principles_cleanup import GoldenPrinciplesCleanup

cleanup = GoldenPrinciplesCleanup()
manifest = cleanup.generate_all(
    principles_file=Path(".claude/principles.yaml"),
    output_file=Path("docs/exec-plans/cleanup-tasks.yaml"),
   
    dry_run=False,
)
cleanup.publish_to_shared_state(manifest)

Output Schema

docs/exec-plans/cleanup-tasks.yaml contains a CleanupTaskManifest:

Each CleanupTask entry:

Example entry

- id: "cleanup-P001-src-api-views-py"
  principle_id: "P001"
  principle_category: "architecture"
  severity: "blocking"
  title: "Enforce repository layer for all DB queries (P001)"
  scope:
    - "src/api/views.py"
    - "src/api/orders.py"
  description: |
    Principle P001 (architecture/blocking) is violated in 2 file(s).

    Rule: All database queries must go through the repository layer

    Affected files:
      - src/api/views.py:88  — direct db.session usage in view layer
      - src/api/orders.py:42 — Model.query called outside repository

    Refactoring steps:
      1. Create or update src/repositories/user_repository.py with the query logic.
      2. Import and call the repository from the view functions.
      3. Run `/harness:lint --gate principles` to verify zero remaining violations.
      4. Update or add unit/integration tests covering the refactored code.
  pr_title: "refactor: enforce P001 architecture across src/api/views.py, src/api/orders.py"
  pr_body: |
    ## What & Why
    ...
  generated_at: "2026-03-22T10:00:00Z"
  status: "pending"

Integration with Other Skills

Key Files

Prerequisites

• PyYAML must be installed: uv add pyyaml
• Pydantic v2 must be installed: uv add 'pydantic>=2.0'
• .claude/principles.yaml must exist (run /define-principles to create it)
• For the harness gate path: uv and harness_skills package must be available