dark-code-skills

Runs a seven-dimension comprehension review on a code change before it ships: credential exposure, cross-service side effects, blast radius, state/persistence mismatch (the Kiro pattern — AI treating persistent infrastructure as ephemeral), token TTL management, implicit assumptions, and whether the change would be explainable by the person shipping it. Produces a COMPREHENSION_ARTIFACT.md with a findings table and a CLEAR / REVIEW REQUIRED / HOLD verdict. Use this skill before merging any AI-generated code, before any change that touches shared resources (Redis, shared databases, message queues), before changes to auth flows or token handling, when reviewing code for dark code risk, or any time you hear "check blast radius", "review for comprehension", "is this safe to ship", "comprehension gate", "pre-merge review", or "will this cause an incident". This skill catches system-level failures that linters, type checkers, and unit tests cannot detect.

Generates three context layer artifacts for a code module: MODULE_MANIFEST.md (structural map — where things connect), BEHAVIORAL_CONTRACTS.md (semantic contracts — what each interface guarantees), and DECISION_LOG.md (philosophical record — why decisions were made, with explicit warnings about what breaks if reversed). Use this skill whenever working on a module that lacks documentation, when the original author has left, before an AI agent modifies an unfamiliar module, when documenting a module after onboarding, when a codebase audit flagged missing context layers, or any time you hear phrases like "document this module", "make this self-describing", "build context layers", "preserve knowledge before the author leaves", or "what does this module do". This skill is especially important for AI-generated code that was never explained by anyone.

Audits a codebase for dark code risk: code that was generated, passed automated checks, and shipped without anyone understanding it. Produces a structured audit report with a hotspot map, comprehension debt scorecard (spec coverage %, context layer coverage %, review depth), ownership gap analysis, top failure scenarios, and a prioritized action plan. Use this skill before a security review, compliance review, or major refactor; when new engineers join and the codebase feels opaque; after a period of high AI-assisted development velocity; quarterly as a health check; or any time you hear "audit for dark code", "comprehension debt", "dark code risk", "what do we not understand about this codebase", "knowledge gap analysis", "who owns what", or "we've been shipping AI code really fast lately". This skill does not recommend "add more monitoring" — it identifies where human comprehension is missing and prescribes structural fixes.

Sets up a project to use the full dark code prevention suite in one step: creates the .claude/comprehension/ directory for comprehension artifacts, adds a ## Dark Code Prevention section to CLAUDE.md (or creates CLAUDE.md if missing), creates docs/dark-code-audit/ for audit reports, and runs an initial dark-code-audit to baseline the project's current comprehension debt. Use this skill when starting to use the dark code suite on a new project, when onboarding a codebase to dark code prevention practices, or any time you hear "set up dark code prevention", "initialize the dark code suite", "add comprehension gate to this project", or "how do I start with dark code practices here".

Assembles a data flow narrative from MODULE_MANIFEST.md and BEHAVIORAL_CONTRACTS.md context files, answering the explainability question: "What does the system do with [data type] for [user journey]?" Use before a compliance or security review, when a dark-code-audit flags "Explainability: Partial", when onboarding a new engineer who needs to understand data flows, or when preparing for GDPR, EU AI Act, or SOC 2 review. Reads context layers across the codebase, interviews for gaps, and writes docs/data-lineage/YYYY-MM-DD-<name>.md with a confidence rating. Invoke as: /generate-data-lineage (all PII-touching flows in the codebase) /generate-data-lineage --journey user-signup (specific user journey) /generate-data-lineage --module path/to/mod (flows for a specific module) /generate-data-lineage --type payment (specific data type)

Generates a per-service EU AI Act system card documenting AI tool usage, risk classification, human oversight mechanisms, and limitations. Use for any service where AI tools contribute to code generation, decision support, or automated processing — especially before the August 2026 EU AI Act deadline. Use when dark-code-audit flags AI-heavy services, when preparing a compliance package for a regulator or enterprise customer, or when the organization needs to document its AI practices. Reads MODULE_MANIFEST.md and BEHAVIORAL_CONTRACTS.md, conducts a structured interview, and writes docs/compliance/eu-ai-act-system-card-<service>-YYYY-MM-DD.md. Invoke as /generate-eu-ai-act-system-card path/to/service or with --risk-level limited|general|high.

Generates a draft GDPR Article 30 Record of Processing Activities (ROPA) from MODULE_MANIFEST.md and BEHAVIORAL_CONTRACTS.md context files. Use when preparing for a GDPR audit, when a dark-code-audit flags PII-handling services with incomplete documentation, or when building a compliance package. Reads context layers across the codebase, groups them into logical processing activities, auto-populates what it can, and interviews the user for fields that require human judgment (legal basis, purpose, international transfers). Writes docs/compliance/gdpr-ropa-YYYY-MM-DD.md. Invoke as /generate-gdpr-ropa or /generate-gdpr-ropa --module path/to/module for a single module entry.

Generates a tenant isolation test scaffold for a module's shared resource writes. Use after the comprehension gate issues REVIEW REQUIRED with an isolation evidence question on a new cache write or shared database write. Also use when adding a new shared resource write to a module that already has BEHAVIORAL_CONTRACTS.md, or when auditing an existing shared resource write that has never been tested for isolation. Reads the target module or file, identifies the resource and key structure, generates three test cases (same-tenant read, cross-tenant isolation, key collision), writes tests/isolation/<module>-isolation.test.<ext>, and updates BEHAVIORAL_CONTRACTS.md with an "Isolation guarantee" field. Invoke as: /generate-isolation-tests path/to/module /generate-isolation-tests path/to/module --interface InterfaceName /generate-isolation-tests path/to/file:line

Aggregates COMPREHENSION_ARTIFACT.md files into a SOC 2 CC8 Change Management evidence package. Use when preparing for a SOC 2 Type II audit, when a SOC 2 auditor asks for Change Management evidence, or quarterly to maintain an ongoing evidence package. Scans .claude/comprehension/ for all artifacts, correlates with git history, identifies control gaps (significant changes with no gate review), interviews the user about gap context, and writes docs/compliance/soc2-cc8-evidence-YYYY-MM-DD.md. Invoke as /generate-soc2-evidence, optionally with --period YYYY-MM-DD YYYY-MM-DD or --control CC8.

Advisory pre-flight check before multi-step AI agent tasks that will modify code or infrastructure. Use before delegating any multi-step task to an AI agent (Claude subagent, Codex, CI automation, or similar) that will touch module source files, databases, queues, or shared resources. Also use when starting any agentic session that will write to production infrastructure, when the task plan includes deletion, recreation, or schema changes, or any time you hear "run an agent on", "have Claude handle", "automate this across modules", or "let the agent figure it out". Reads MODULE_MANIFEST.md for affected modules, cross-checks planned operations against permitted/restricted operations and DECISION_LOG.md warnings, and produces an advisory checklist before the task begins. Advisory only — does not block. Invoke as /pre-agent-task or /pre-agent-task --modules path/to/a path/to/b

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Also use when a session-start warning indicated no spec was found for the current branch, when working on AI-generated code that needs a comprehension anchor, or any time you hear "write a spec", "spec this out", "define requirements", "what are we building", or "let's plan this first". Do not skip this skill because the task seems simple — even a two-line spec is better than none, and the spec-as-eval step it adds is what connects Layer 1 (specification) to Layer 3 (comprehension gate).