# Supercharge

> Evidence-first, read-only engineering-health assessment for application, architecture, and platform repositories. Use it for recurring focused code, architecture, delivery, operability, test, or supply-chain findings; optional read-only external evidence; and redacted assessment artifacts.

- Skill: `asteroid-belt/supercharge` (Agent Skill, multi-file: 41 files)
- Install (CLI): `npx skillmds@latest add asteroid-belt/supercharge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asteroid-belt/supercharge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: asteroid-belt (https://skillmd.com/u/asteroid-belt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asteroid-belt/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.

| Mode | Scope | Completion behavior |
|---|---|---|
| `quick` | Changed-file signals, dependency/runtime currency, and obvious quality observations. | Records findings and closes the assessment. |
| `standard` | Every detectable focused assessment. | Records findings and closes the assessment. |
| `assessment-only` | Every selected assessment and all session artifacts. | Stops after artifacts without requesting review decisions. |
| `domain-limited` | Only user-named assessment domains; records omitted domains as exclusions. | Records in-scope findings and closes the assessment. |

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.

| Artifact | Purpose |
|---|---|
| `improvements.md` | Human-readable evidence-backed backlog and review interface. |
| `improvements.json` | Versioned structured findings, fingerprints, statuses, and safe recurrence data. |
| `session-state.md` | Resumable mode, consent, availability, review, and closure state. |
| `report.md` | Final assessment outcome without implementation claims. |
| `sarif/` | Optional; 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

```text
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.

| When | Required reference | Purpose |
|---|---|---|
| Detect and consent | [INTEGRATION_CONTRACT.md](references/INTEGRATION_CONTRACT.md) | Consent, adapter scope, read-only evidence, redaction, and unavailable results. |
| Dependency/runtime | [DEPENDENCY-RUNTIME-ASSESSMENT.md](references/DEPENDENCY-RUNTIME-ASSESSMENT.md) | Read-only ecosystem inventory and upgrade strategy. |
| Test coverage | [TEST_COVERAGE_ASSESSMENT.md](references/TEST_COVERAGE_ASSESSMENT.md) | Policy, characterization evidence, and refactoring safety gate. |
| Codebase foundations | [CODEBASE_FOUNDATIONS_ASSESSMENT.md](references/CODEBASE_FOUNDATIONS_ASSESSMENT.md) | Evidence-backed documentation and quality-tool recommendations. |
| Code quality | [CODE_QUALITY_ASSESSMENT.md](references/CODE_QUALITY_ASSESSMENT.md) | Qualitative maintainability findings. |
| Code complexity | [CODE_COMPLEXITY_ASSESSMENT.md](references/CODE_COMPLEXITY_ASSESSMENT.md) | Configuration-aware structural metrics and hotspots. |
| Architecture | [ARCHITECTURE_ASSESSMENT.md](references/ARCHITECTURE_ASSESSMENT.md) | Boundaries, dependencies, ownership, compatibility, and quality attributes. |
| Delivery/infrastructure | [DELIVERY_AND_INFRASTRUCTURE_ASSESSMENT.md](references/DELIVERY_AND_INFRASTRUCTURE_ASSESSMENT.md) | CI/CD, IaC, deployment, rollback, environments, and blast radius. |
| Operability/reliability | [OPERABILITY_AND_RELIABILITY_ASSESSMENT.md](references/OPERABILITY_AND_RELIABILITY_ASSESSMENT.md) | Ownership, SLOs, telemetry, alerting, recovery, and incident readiness. |
| Test effectiveness | [TEST_EFFECTIVENESS_ASSESSMENT.md](references/TEST_EFFECTIVENESS_ASSESSMENT.md) | Flakiness, isolation, assertions, test layers, and defect detection. |
| Security/supply chain | [SECURITY_AND_SUPPLY_CHAIN_READINESS.md](references/SECURITY_AND_SUPPLY_CHAIN_READINESS.md) | Advisory readiness evidence for controls and supply-chain practices. |
| Normalize and approve | [IMPROVEMENTS_TEMPLATE.md](references/IMPROVEMENTS_TEMPLATE.md) | Backlog presentation and approval selection. |
| Structured artifact | [IMPROVEMENTS-SCHEMA.json](references/IMPROVEMENTS-SCHEMA.json) | JSON schema, lifecycle vocabulary, and SARIF constraints. |
| Prioritize | [SEVERITY-MATRIX.md](references/SEVERITY-MATRIX.md) | Evidence-based severity, recurrence, and critical finding treatment. |
| Enforce authority boundaries | [SAFE-REFACTORING-RULES.md](references/SAFE-REFACTORING-RULES.md) | Consent, review decisions, and no-mutation boundary. |
| Record outcome | [REPORT-TEMPLATE.md](references/REPORT-TEMPLATE.md) | Final assessment report structure. |

## 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](references/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](references/IMPROVEMENTS_TEMPLATE.md), [IMPROVEMENTS-SCHEMA.json](references/IMPROVEMENTS-SCHEMA.json), and [SEVERITY-MATRIX.md](references/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](references/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`:

```markdown
# 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

| Need | Use |
|---|---|
| Assess optional external evidence safely | Phase 2 + `INTEGRATION_CONTRACT.md` |
| Assess dependencies and runtimes | `DEPENDENCY-RUNTIME-ASSESSMENT.md` |
| Require behavior safety before future refactoring | `TEST_COVERAGE_ASSESSMENT.md` |
| Assess code/documentation/tooling foundations | `CODEBASE_FOUNDATIONS_ASSESSMENT.md` |
| Assess qualitative code or structural complexity | `CODE_QUALITY_ASSESSMENT.md` / `CODE_COMPLEXITY_ASSESSMENT.md` |
| Assess architecture, delivery, reliability, tests, or supply chain | Corresponding focused assessment reference |
| Record review decisions | `improvements.md` + `IMPROVEMENTS_TEMPLATE.md` |

## 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.