ai-engineering-harness

Write, refactor, restructure, edit, or audit technical documentation using the Diátaxis framework (tutorials, how-to guides, reference, explanation). Produces clear, concise, scannable docs and fights the default tendency toward bloated, over-explained AI prose. Use this skill for ANY documentation work — README and CONTRIBUTING files, API/reference docs, runbooks, guides, getting-started pages, conceptual write-ups, docs-site content, or doc reviews — even when the user just says "document this," "write docs for X," "clean up these docs," "explain how this works in the docs," or "what's missing from our documentation." If the deliverable is documentation, reach for this skill rather than writing prose freehand.

Retroactively create Linear tickets and PRs from untracked commits. Use for commits without tickets, "founder mode", or formalizing experimental work.

Create well-structured git commits from analyzed changes. Use when the user asks to commit, save work, or create a commit.

Find architectural friction and propose deep-module refactors as RFC issues. Use to improve architecture, find refactoring opportunities, or deepen shallow modules.

Initialize the AI Engineering Harness (AGENTS.md + thoughts/ structure). Use on /init_harness or when setting up the harness in a repo.

Interview the user relentlessly to stress-test a plan or design. Use to validate design decisions, "drill in", or "ask me questions" before implementation.

Observability Driven Development (ODD) — design the trace before the feature. Use for "ODD", "instrument first", "telemetry-driven", or a local OTel feedback loop with the Aspire dashboard.

OpenTelemetry Collector configuration — receivers, processors, exporters, pipelines, sampling, deployment. Use for Collector/OTLP/Prometheus config tasks.

OpenTelemetry orchestrator — routes observability, telemetry, tracing, metrics, logging, OTel SDK, Collector, semantic-conventions, or OTTL requests to the right sub-skill.

Application-side OpenTelemetry SDK setup — traces, metrics, structured logging across Node.js, Go, Python, Java, .NET, Ruby. Use for instrumenting app code with the OTel SDK.

OTTL (OpenTelemetry Transformation Language) reference — syntax, contexts, patterns (redaction, normalization, enrichment, filtering), functions. Use for OTTL in Collector processors.

OpenTelemetry semantic conventions — attribute naming, placement, stability/versioning, legacy→current migration. Use for OTel attribute naming and convention questions.

Generate comprehensive PR descriptions following repository templates. Use when creating, updating, or describing a pull request for review.

Break a PRD into independently-workable, vertical-slice issues as markdown files in issues/. Use to turn a PRD into concrete tasks ordered by dependencies.

Test-driven development via the red-green-refactor loop. Use for TDD, "red-green-refactor", test-first development, or tests that survive refactors.

Generate a structured PRD from a client brief, written as issues/prd.md. Use to turn a client request or rough idea into a PRD.

Observability Driven Development (ODD) — design the trace before the feature. Auto-activates when the user wants to "drive with observability", "ODD", "instrument first", "narrative-first", "telemetry-driven", or wants to set up a local OTel feedback loop with the Aspire dashboard. Pairs with /validate_telemetry to verify behaviour against a written narrative.

Create detailed, actionable implementation plans through an interactive, iterative process

Observability Driven Development (ODD) — design the trace before the feature. Auto-activates when the user wants to "drive with observability", "ODD", "instrument first", "narrative-first", "telemetry-driven", or wants to set up a local OTel feedback loop with the Aspire dashboard. Pairs with /validate_telemetry to verify behaviour against a written narrative.

OpenTelemetry orchestrator — auto-activates on observability, telemetry, tracing, metrics, logging, OTel SDK, Collector, semantic conventions, or OTTL requests. Routes to the correct sub-skill.

Validate locally-emitted telemetry against a written narrative spec, or run a generic health check on the local OTel stack. Delegates to the observability-driven-development skill's Validation section.

Create detailed, actionable implementation plans through an interactive, iterative process, leveraging Gemini CLI tools for research and documentation.

Observability Driven Development (ODD) — design the trace before the feature. Auto-activates when the user wants to "drive with observability", "ODD", "instrument first", "narrative-first", "telemetry-driven", or wants to set up a local OTel feedback loop with the Aspire dashboard. Pairs with /validate_telemetry to verify behaviour against a written narrative.

OpenTelemetry orchestrator — auto-activates on observability, telemetry, tracing, metrics, logging, OTel SDK, Collector, semantic conventions, or OTTL requests. Routes to the correct sub-skill.

Query GitHub for pull requests, issues, notifications, and project boards using the gh CLI. Use this skill whenever the user asks about their GitHub activity, PRs needing review, open issues, project board status, or wants to summarize GitHub conversations. Trigger on phrases like: "what PRs need my attention", "show my open issues", "what's happening in [repo]", "summarize this PR", "check my GitHub notifications", "what's on my project board", "issues I own", "PRs I need to review", "what needs my attention on GitHub", "GitHub status", "show me PRs for [component]", "open issues in [org/repo]", or any reference to pull requests, issues, reviews, or GitHub project boards. Also trigger when the user wants to feed GitHub items into Todoist or another task manager — this skill surfaces the data, then the user can hand off to the Todoist skill.

Explore a codebase to find architectural friction, propose deep-module refactors as RFC issues. Use when the user wants to improve architecture, find refactoring opportunities, deepen shallow modules, or make a codebase more AI-navigable and testable.

Interview the user relentlessly about a plan or design until reaching shared understanding. Walks down each branch of the decision tree, resolving dependencies one-by-one. Use when the user wants to stress-test a plan, asks to be interviewed, says "drill in", "ask me questions", or wants to validate design decisions before implementation.

Break a PRD into independently-workable, vertical-slice issues written as local markdown files in issues/. Use when the user wants to turn a PRD into a list of concrete, demoable tasks ordered by dependencies.

Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", asks for test-first development, or wants integration-style tests that survive refactors.

Generate a PRD from a client brief and write it as issues/prd.md. Interviews the user about problem and solution, sketches deep modules, and writes a structured PRD. Use when the user wants to turn a client request or rough idea into a structured PRD.

Explore a codebase to find architectural friction, propose deep-module refactors as RFC issues. Use when the user wants to improve architecture, find refactoring opportunities, deepen shallow modules, or make a codebase more AI-navigable and testable.

Interview the user relentlessly about a plan or design until reaching shared understanding. Walks down each branch of the decision tree, resolving dependencies one-by-one. Use when the user wants to stress-test a plan, asks to be interviewed, says "drill in", "ask me questions", or wants to validate design decisions before implementation.

Break a PRD into independently-workable, vertical-slice issues written as local markdown files in issues/. Use when the user wants to turn a PRD into a list of concrete, demoable tasks ordered by dependencies.

Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", asks for test-first development, or wants integration-style tests that survive refactors.

Generate a PRD from a client brief and write it as issues/prd.md. Interviews the user about problem and solution, sketches deep modules, and writes a structured PRD. Use when the user wants to turn a client request or rough idea into a structured PRD.

OpenTelemetry Collector configuration — receivers, processors, exporters, pipelines, sampling, deployment. Covers OTLP, Prometheus, filelog, hostmetrics; processor ordering; pipeline design; head/tail sampling; and RED metric derivation via signaltometrics.

Application-side OpenTelemetry SDK setup — traces, metrics, structured logging across Node.js, Go, Python, Java, .NET, Ruby. Prescriptive guidance for resource attributes, span design, metric instrument selection, sensitive data handling, and validation.

OTTL (OpenTelemetry Transformation Language) reference — syntax, contexts, common patterns (redaction, normalization, enrichment, filtering), error handling, and complete function reference for Collector processors.

OpenTelemetry semantic conventions — attribute naming, placement across telemetry levels, stability/versioning, legacy→current migration, and registry namespace reference.

OpenTelemetry Collector configuration — receivers, processors, exporters, pipelines, sampling, deployment. Covers OTLP, Prometheus, filelog, hostmetrics; processor ordering; pipeline design; head/tail sampling; and RED metric derivation via signaltometrics.