Supercharge

Supercharge: Engineering-Health Orchestrator

Overview

Supercharge conducts a safe, evidence-first engineering-health session for an existing repository. It coordinates focused assessment references, records what could and could not be assessed, normalizes and redacts findings, and presents a user-selectable improvement backlog. SKILL.md owns workflow and boundaries; domain detection, policy, thresholds, and remediation guidance belong in the linked references.

Use Supercharge for periodic maintenance, before a major planning effort, after substantial AI-assisted development, or when an application, architecture, or platform codebase needs evidence-backed improvement opportunities.

What Supercharge Does

1. Detects the selected mode, repository scope, stack, policies, exclusions, quality tools, and available local evidence.
2. Requests explicit per-session consent before every optional external read.
3. Coordinates selected focused assessments without changing the repository or external systems.
4. Normalizes, deduplicates, redacts, prioritizes, and tracks recurring findings.
5. Writes a human-readable improvement backlog and structured JSON artifact.
6. Records user review decisions without treating them as authorization to act.
7. Closes the assessment in a final report without claiming implementation or verification that has not occurred.

What Supercharge Does Not Do

• Install tools, change source, dependencies, runtime pins, lockfiles, CI, documentation, infrastructure, cloud state, or external systems.
• Query an external provider before session-specific read consent is approved.
• Treat unavailable evidence as a healthy or passing result.
• Infer improvement approval from severity, discussion, or lack of objection.
• Create an implementation plan, direct another skill to create one, or execute a change. A user decision is assessment state, not mutation authority.

Operating Modes

The standard mode is the default. It attempts every detectable assessment and records unavailable or manual-review evidence nonblockingly.

An explicit user request chooses a non-default mode. If no mode is named, proceed with standard.

Session Artifacts

Keep one session in docs/supercharge/YYYY-mm-dd/:

The required dated artifact set is docs/supercharge/YYYY-mm-dd/{improvements.md,improvements.json,report.md,session-state.md}. An optional docs/supercharge/YYYY-mm-dd/sarif/ directory may contain only locatable static-analysis findings.

Reuse a dated directory only for an explicit resumed session. Do not overwrite a finalized outcome silently; record the resume decision and current revision in session-state.md.

Core Workflow

1. DETECT MODE, SCOPE, AND POLICY
        ↓
2. EXTERNAL READ CONSENT
        ↓
3. FOCUSED ASSESSMENTS
        ↓
4. NORMALIZE, REDACT, AND PRIORITIZE
        ↓
5. WRITE IMPROVEMENTS ARTIFACTS
        ↓
6. RECORD USER DECISIONS
        ↓
7. WRITE AND CLOSE ASSESSMENT ARTIFACTS

Every assessment is read-only. If a binary, registry, policy, connector, environment, or source is unavailable, write an unavailable or manual review result with a precise reason and continue remaining work. Availability is never a pass/fail health result.

Reference Index

Read the relevant focused reference before running its assessment. Read the shared contracts before external access, normalization, prioritization, or assessment closure.

Phase 1: Detect Mode, Scope, and Policy

Identify the selected operating mode, codebase revision and dirty-worktree state, stack, manifests, runtime declarations, tests, quality tools, CI, documentation, architecture, delivery configuration, and configured exclusions. Repository and CI policy is authoritative over adapter, native-tool, and Supercharge advisory defaults.

Record selected domains, omitted domains, available commands, and unavailable local capabilities in session-state.md. Do not install a tool or alter project configuration to improve assessment coverage.

Phase 2: External Read Consent

Read INTEGRATION_CONTRACT.md before this phase.

Determine which optional providers could answer an assessment question. Before each external query, present the adapter, smallest requested read scope, and purpose in a consent table. Wait for explicit approval for that session.

GitHub/GitHub Actions, GitLab/GitLab CI, Terraform/OpenTofu, Kubernetes, and OpenTelemetry-compatible sources are first-class targets. A denied, unsupported, expired, rate-limited, or unavailable source becomes a source-located unavailable or manual review record; it does not block local evidence or other domains.

Phase 3: Run Focused Assessments

Read every selected domain reference and run every detectable domain in standard mode. Preserve the distinction between assessment availability and follow-up status. Do not combine scope-specific evidence from different domains without retaining the originating assessment.

Suggested standard sequence:

1. Dependency/runtime and test coverage.
2. Codebase foundations, code quality, and code complexity.
3. Architecture and delivery/infrastructure.
4. Operability/reliability and test effectiveness.
5. Security/supply-chain readiness.

The sequence is organizational only; independent read-only assessments may run in parallel when their evidence sources do not overlap unsafely.

Phase 4: Normalize, Redact, and Prioritize

Read IMPROVEMENTS_TEMPLATE.md, IMPROVEMENTS-SCHEMA.json, and SEVERITY-MATRIX.md.

Write improvements.md and improvements.json. For every finding, retain its stable SC- ID, canonical fingerprint, assessment, category, normalized target, safe evidence references, policy context, confidence, availability, lifecycle status, recommendation, and recurrence metadata. Redact sensitive values before writing any artifact.

Deduplicate only records with the same canonical fingerprint. Keep different assessments or policy contexts distinct even when descriptions are similar. Apply project/CI policy first, adapter-native configuration second, native tool defaults third, and advisory defaults last.

Place Critical Findings first in the backlog. Each must show safe evidence, policy context, confidence, and the smallest safe next step. Critical findings remain nonblocking and proposed until the user records a review decision.

Phase 5: Record User Decisions

Present the completed improvements.md and ask for a decision on each proposed ID. The user may approve, defer, block, or exclude an item. assessment-only ends after artifacts and does not request decisions. Record every decision in improvements.md, improvements.json, and session-state.md. An approved decision means the user reviewed the recommendation; it does not create a plan, authorize a change, or assign work to another skill.

Phase 6: Record the Outcome

Read REPORT-TEMPLATE.md.

Write or update report.md with the selected mode, scope, revision, policy, availability, consented sources, critical findings, recurrence, review state, and the closed assessment outcome.

Use assessment-complete when the selected work has been assessed and recorded. Use awaiting-review, deferred, or blocked when that state better describes the session. Never report a repository change as completed or verified.

Session State Tracking

For a multi-session assessment, write docs/supercharge/YYYY-mm-dd/session-state.md:

# Supercharge Session State

## Current State
[mode, phase, new/resumed state, and next action]

## Scope and Policy
- Revision / dirty worktree: [state]
- Domains selected or excluded: [list and reason]
- Authoritative policy and exclusions: [sources]

## External Read Consent
| Adapter | Requested scope | Consent | Granted scope | Availability / reason |
|---|---|---|---|---|
| [adapter] | [scope] | proposed / approved / denied | [scope] | [status] |

## Assessment Availability
| Assessment | Availability | Policy / Evidence Source | Key Result |
|---|---|---|---|
| [each selected assessment] | assessed / unavailable / manual review | [safe source] | [summary] |

## Improvement Decisions
| ID | Status | User decision / owner | Review or unblock action |
|---|---|---|---|
| [SC-id] | proposed / approved / deferred / blocked / excluded | [decision] | [action] |

## Assessment Closure
- Outcome: [assessment-complete / awaiting-review / deferred / blocked]
- Closed at: [time or next review date]

## Resume Instructions
[next phase, required reference, and exact action]

Quick Reference

Closed Assessment Boundary

Supercharge is an assessment and reporting workflow only. It does not package findings for planning, prescribe an implementation successor, or claim change execution or verification. Users may independently choose their next action; that choice is outside the assessment contract.