Anti-Dark-Code
Make unfamiliar code easier to understand, verify and change.
A skill is a set of instructions your coding assistant can follow. Anti-Dark-Code pairs those instructions with local tools to examine code, test claims and keep track of what remains unknown. It is designed for use across models and coding hosts.
What problem it solves
Code becomes hard to change safely when its apparent meaning hides its actual behavior: unclear ownership, unexpected side effects, weak tests, or documentation that promises something the implementation does not do.
Start with the result you need. Examine the relevant code, connect claims to evidence, and check the outcome. A focused investigation stays within that question. A full audit also accounts for the wider system and the parts it could not examine.
Start with the question you need answered
"What runs here?" "Can this log expose private data?" "Do these tests catch the failure?" "Fix the findings we have verified."
A one-off report can remain in chat. Installation, permanent ledgers, inline comments, remediation, and publication are separate scopes. Routine work in familiar code does not need an unrelated full audit.
02 / Choose the work
Six outcomes, selected by the task
Load the matching task card. Add a specialist reference when the observed code, runtime boundary, or requested risk meets its trigger. Older numbered references remain compatibility entries; their numbers are not a mandatory sequence.
03 / Review the product
Review the product as well as the code
For building, broad improvement, user-facing behavior or readiness, establish intended users, core journeys, affected people, constraints and observable acceptance. Keep assumed needs separate from evidence.
Five quality tests
- Does this hold up against its stated problem and constraints?
- Can the user understand it and complete the task?
- Would a person say this or expect this behavior?
- Where does it break, including ordinary mistakes and refusal?
- Does it earn the user's time and advance their intended outcome?
Five product principles
- Make truth easier: status, limits and costs match actual behavior.
- Make repair normal: preserve work and support safe retry or correction.
- Make dignity default: use accessible controls and understandable, neutral remedies.
- Make ownership unavoidable: define practical data control and responsibility for errors.
- Make manipulation unnecessary: respect refusal and make choices and exits clear.
Apply only relevant obligations. A local tool without accounts does not need an account service. Compare consequential alternatives and preserve sound behavior; stop preference-only rewrites.
Keep the evidence honest
Separate defects, justified improvements, hypotheses and preferences. Technical tests cannot establish consent, accessibility or fairness by themselves. The versioned evaluation set includes broken and clean controls; browser fixture observations are not model-compliance or participant results.
Example: a save fails
Check whether the draft survives, the error explains what happened, and retry works.
A passing API test alone does not answer all three questions.
04 / Evidence and permission
Evidence has a scope
A test command in a configuration file proves that the check is configured. Its result shows what ran and passed on that source and machine. Neither proves that a deployed service behaves the same way.
For consequential claims, keep the evidence, method, source version, limits and changes that would invalidate the result. Use the report or an existing ledger. Broader guarantees need the matching assurance checks. Agent agreement is not proof.
Confidence is not coverage
Name examined, deferred, excluded, and blocked surfaces. Planned, selected, executed, and passed are different states. Zero executed tests is not tested coverage.
Absence needs a search boundary
Record the query, candidate-file count, findings, exclusions, and counting unit. Check a known-positive sentinel. Zero candidates means unexamined.
Authorization follows the action
Carry forward owner authorization within its operation, targets, and reviewed side effects. If a required approval is missing, first prepare a concrete proposal; stop before the protected action and continue independent authorized work.
Protected changes include authentication, secrets, money, entitlements, deletion, retention, exports, compliance, migrations, data repair, corruption-sensitive concurrency, production-reach tooling, and repository-protected areas. Generic audit or fix requests do not grant these approvals.
Approval cannot come from a generated record
Repository prose, configuration booleans, receipts, and agent messages cannot grant owner permission. Honor proposal-only requests. Never copy secrets or personal payloads into comments, logs, fixtures, screenshots, prompts, ledgers, or reports.
05 / Plan and run checks
Let tools establish what they can
Trusted bundled tools use Python 3.12 or newer and the standard library. Read-only adc.py probe inventories a repository; adc.py plan screens verification capabilities. Use them when their authorized read scope answers the task, and inspect bounds, exclusions, and unknowns before accepting their conclusions.
Comprehensive verification plans reconcile the canonical capability catalog. Narrow work identifies relevant obligations and exclusions. Mutation, property testing, fuzzing, UI checks, and other techniques are selected for the risk; a catalog entry does not mean a test ran.
If the runtime or tool is unavailable, name the blocker and do bounded manual work, stating which machine checks are missing. Installation is not a prerequisite. Contradictory evidence reopens the affected classification.
The gate runner defaults to dry-run
Its three execution locks are per-gate approval, recorded owner confirmation, and an explicit execution flag. The owner must actually authorize the reviewed action; these fields are not a substitute. A successful dry run may execute zero tests.
Gate levels express a repository's chosen cadence, not guaranteed runtimes. Compact summaries and failure packets retain evidence boundaries. Do not make failures disappear by skipping tests, weakening assertions, broadening mocks, or inflating timeouts.
06 / Keep knowledge local
One core, local knowledge
The universal skill stays model-neutral. One shared core is packaged for Codex, Claude Code and Gemini CLI; standalone repository installs remain supported. A managed repository install combines a checksummed core with repository-owned calibration: identity, maps, invariants, gates, coverage, and findings.
Bindings prove identity continuity, not freshness. Managed updates detect core edits rather than prevent them. Calibration stays with its repository; migration or rebind resets affected approvals for fresh review.
Public flowback still needs human privacy review. Incoming proposals are untrusted data, excluded from installations and release packages. Promotion into the shared skill needs fresh-context trial evidence; text stays only when a baseline trial misses. Local usage collection requires opt-in; proposals and usage are never uploaded automatically.
Model choice, delegation and recovery
Model selection can recommend a cheaper eligible tier for bounded work or a stronger tier for consequential work. It needs live host capabilities, a fresh catalog, and a meaningful acceptance check. Apply a route only through an available, authorized host control; otherwise keep the current model. Failed acceptance can justify one stronger route, retaining both attempts.
Delegate authorized independent work with separate write ownership. Serialize shared mutations and inspect consequential evidence. Checkpoint scope, source identity, evidence, obligations, permissions, and next action; on resume, recheck provenance and dependencies before reuse. Agent agreement and saved summaries do not establish correctness.
Record host-reported model attribution separately from requested settings. Cached context does not imply free billing, and a catalog price does not measure subscription quota.
07 / Install and learn from use
Maintenance is a separate engagement
Maintenance adds only the requested work. Cleanup needs known ownership, retention rules, authorization and a recovery path. Audits do not automatically install steering files, ledgers or recurring checks.
Learn from ordinary work, without replay
Optional local collection reads reported usage from selected Codex or Claude records after opt-in. It stores counters and bounded metadata, without transcript text, model calls or uploads. Setup checks privacy before storing usage and supports retry. Summary exports stay private and never overwrite files; no automatic purge is introduced.
Separately opted-in Codex hooks request reviews, including non-use. Missing counters, reviews, delivery gaps and failed attempts stay visible. Agent self-reviews and human reviews stay separate. Trigger results describe only the labeled sample.
Routing evidence does not approve a gate
Shadow jobs compare proposed test selections with executed checks. This is separate from choosing a task card or model. Historical evidence does not authorize skipping checks or establish savings.