Progressive Disclosure Entry

This entrypoint stays concise and keeps full operational context in archived references.

Use

• Use this skill as the canonical Harness Engineering bug-fixing stage.
• For full stage policy, workflow details, and examples, load the archived full guide.

Philosophy

• Reproduce first, then diagnose, then fix.
• Root-cause clarity beats patch velocity.
• Investigate before proposing changes, and keep the causal chain from trigger to symptom explicit.

When to use

• Use when regressions, runtime failures, or tracker defects require evidence-backed debugging.
• Use when issue reproduction and verification are required before coding changes.
• Use when prior fix attempts failed and the request needs disciplined root-cause analysis instead of more trial-and-error edits.
• Use when the user starts a QA session or reports bugs conversationally and wants durable Linear issues.

Inputs

• Symptom report, repro context, and affected scope.
• Logs, traces, tests, and relevant code paths.
• Optional issue-tracker reference or pasted issue context.
• Relevant CONTEXT.md when issue language uses project-specific terms.
• Execution permission: diagnosis-only or diagnose-and-fix.
• Optional QA-intake mode when reports need Linear issue filing before diagnosis.

Outputs

• Reproduction evidence, root-cause analysis, fix scope, and verification outcome.
• Linear issue payloads or URLs for QA intake, including single/breakdown decision and blocker links.
• Clear next action when blocked or when diagnosis is complete but remediation is not yet chosen.
• Regression test recommendation and why existing checks missed the issue when that is knowable.
• Include schema_version: 1 when structured output is requested.

Procedure

1. Parse intake first: symptom report, tracker context, expected behavior, and any prior failed attempts.
2. If the request is a QA session or conversational report, run QA intake: ask at most 2-3 focused questions, lightly inspect domain language, decide single issue vs breakdown, and file or prepare Linear issue payloads before diagnosis.
3. Compare issue language with CONTEXT.md when present so aliases or domain misunderstandings do not become false bug scope.
4. For runtime, CLI, startup, agent-routing, or session-log failures, collect bounded runtime evidence before reproduction: identify relevant logs/config paths, read only tails or targeted matches, capture [ERROR]/[WARN] markers, and state when logging began too late to prove the original failure.
5. Reproduce and stabilize the failing behavior before proposing changes.
6. Trace backward from the symptom to the point where valid state first became invalid.
7. Test one hypothesis at a time, and for uncertain links require a prediction that can confirm or falsify the chain.
8. Present the root cause, proposed fix scope, and test recommendations before remediation when the request is diagnosis-first or confidence is still settling.
9. When remediation is in scope, check workspace safety, prefer failing-test-first validation, apply the minimal fix, and verify no regressions.

Validation

• Confirm reproduction and post-fix verification are both recorded.
• Confirm the causal chain from trigger to symptom is explicit before fix work proceeds.
• Confirm fix addresses root cause instead of symptom masking.
• Confirm Linear issue wording, expected behavior, and domain terms agree or explicitly name the mismatch.
• Confirm QA-created Linear issues avoid file paths and line numbers, include reproduction steps, and use behavior-focused domain language.
• Confirm blocked or partial outcomes name the exact missing condition, evidence gap, or next safest route.
• Fail fast: stop at first failed gate and do not proceed.

Constraints

• Redact secrets, credentials, tokens, and sensitive data by default.
• Do not mark issue fixed without successful verification evidence.
• Do not skip straight to edits when reproduction or root-cause evidence is still missing.
• Do not patch around a domain-model contradiction; route to he-deepen-spec when behavior meaning is unclear.
• Do not create GitHub issues or ADRs for QA intake unless the user explicitly overrides the Linear-first project convention.
• Do not over-interview during QA intake; ask only the minimum short questions needed to file a durable issue.
• Do not use shotgun debugging or bundle unrelated changes into one bug fix.
• Apply the context-disposition policy: move important still-valid context to references and index it when meaningful; intentionally discard stale, duplicated, unsafe, superseded, or low-signal text.

Anti-patterns

• Skipping deterministic reproduction and guessing a fix.
• Shipping fixes that lack regression checks.
• Accepting a symptom fix when the causal chain prediction failed.
• Treating tracker intake, diagnosis, and issue management as one speculative step.

Examples

• "When the user asks, Can you inspect this regression that started after the auth refactor, reproduce it, and find the root cause before you fix anything?"
• "Please investigate this crash, but stop at diagnosis and test recommendations because I do not want edits yet."
• "Help me validate why the last two quick patches failed and tell me what is actually broken."
• "Can you run a QA session and file Linear issues for each bug I report?"

Full Context

• Canonical contract: ./Infrastructure/references/contract.yaml
• Canonical eval cases: ./Infrastructure/references/evals.yaml
• Canonical task profile: ./Infrastructure/references/task-profile.json
• Compatibility mirror (non-canonical): ./references
• Assets: ./assets
• Assets directory marker: assets/
• Domain model routing: ../../../references/domain-model-routing.md Read when: issue wording may conflict with CONTEXT.md or use a non-canonical project term.
• QA intake routing: ../../../references/qa-intake-routing.md Read when: the user reports bugs conversationally, asks for a QA session, or wants feedback turned into Linear issues.
• Runtime evidence intake: ./Infrastructure/references/runtime-evidence-intake.md Read when: the failure involves logs, startup, CLI/runtime state, agent routing, or debug evidence that may be incomplete. Read when: you need full workflow behavior, diagnosis gates, and fix sequencing. Read when: you need contracts, eval fixtures, anti-patterns, or tracker-intake details. Read when: you need icon/display metadata and invocation policy.
• Subagent routing: ../../../references/subagent-routing.md Read when: you need canonical stage policy and fallback behavior.

Subagent Routing

• Canonical stage map: ../../../references/subagent-routing.md
• Machine-readable policy: ../../../references/routing-map.json
• Resolve available roles from ~/.codex/agents/manifest.json before spawning helpers.
• Apply the mapped stage policy (always, conditional, or manual-only) before delegation.
• If auto-spawn is unavailable, continue inline and explicitly list the roles the user can launch manually.
• If required roles are missing from the manifest, create or install them with ../../../../../Skills/agent-ops/codex-agent-creator/SKILL.md before rerunning delegated coverage.