aiwg/agentic/code/addons/aiwg-utils/rules/debug-source-not-output.md

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# Debug Source Not Output Rules

**Enforcement Level**: HIGH
**Scope**: All tool-using agents across all platforms
**Addon**: aiwg-utils (core, universal)
**Category**: disambiguation

## Overview

When debugging in multi-project or monorepo contexts, agents frequently waste effort analyzing build artifacts instead of navigating to the originating source code. Minified files, compiled output, and bundled vendor code are not the right place to investigate bugs — the source project is.

This rule is a disambiguation heuristic: when you encounter a file that is build output from a child or dependency project, stop and navigate to its source instead of analyzing the artifact.

## Problem Statement

Agents routinely make this mistake:

- Reading minified JavaScript to understand behavior instead of finding the source module
- Debugging a stack trace that points into `node_modules/` without tracing to the originating package source
- Analyzing `dist/` or `build/` files when `src/` exists in the same or a sibling project
- Attempting to interpret compiled output character-by-character when source maps or workspace configs point directly to the real source

This produces wasted effort and incorrect conclusions — minified code is semantically accurate but structurally hostile to comprehension. The source is always the right place to debug.

## Detection Signals

When you encounter any of the following, treat the file as build output and find the source:

| Signal | Meaning |
|--------|---------|
| Minified/single-line file | Compiled artifact — find source project |
| Path contains `dist/`, `build/`, `out/` | Build output directory |
| Path contains `node_modules/` | Installed dependency — trace to package source |
| Path contains `.next/`, `.nuxt/`, `.svelte-kit/` | Framework build output |
| File contains `//# sourceMappingURL=` | Source map available — follow it |
| File starts with `/*! ... */` license banner followed by minified code | Bundled vendor artifact |
| Filename ends in `.min.js`, `.min.css` | Explicitly minified |
| File contains obfuscated variable names (`a`, `b`, `c`, `_0x...`) | Bundled/obfuscated output |
| `generated by` or `@generated` header comment | Code-generated file |

## Mandatory Rules

### Rule 1: Never Debug Build Output When Source Is Available

**FORBIDDEN**:
```
Agent opens dist/main.js to understand why authentication fails.
Agent reads node_modules/express/lib/router/index.js to trace a routing bug.
Agent interprets minified bundle to find a logic error.
```

**REQUIRED**:
```
Agent sees dist/main.js in stack trace → identifies source project → opens src/auth.ts instead.
Agent sees node_modules/express stack frame → checks Express source repo or reads error message
  to understand which Express API is being misused → fixes call site in own code.
Agent sees minified bundle error → follows source map to original source file.
```

### Rule 2: Map Artifacts to Source Projects Before Acting

Before reading any file flagged by detection signals, determine where its source lives:

| Artifact Location | How to Find Source |
|-------------------|--------------------|
| `dist/`, `build/`, `out/` | Look for sibling `src/` directory in same project |
| `node_modules/<pkg>/dist/` | Check if `<pkg>` exists as a workspace package (pnpm-workspace.yaml, lerna.json, turbo.json, `workspaces` in package.json) |
| `.next/`, `.nuxt/` | Framework output — source is always in `src/` or `pages/` of the parent project |
| Git submodule path | `cd` into the submodule directory and debug there |
| Linked dependency | Follow symlink to the linked project's source directory |

### Rule 3: Workspace Config Is a Source Map for Monorepos

If the parent project contains any of these files, it is a monorepo or workspace. Use them to map artifact paths to source packages before debugging:

```
pnpm-workspace.yaml    → lists workspace glob patterns
lerna.json             → lists packages array
turbo.json             → shows pipeline and package graph
package.json           → check "workspaces" field
nx.json                → check projects and targets
rush.json              → check projects array
```

**Required action**: When a stack trace or error points into a build artifact, check for these files at the repo root first. If found, resolve the artifact's package to its workspace source directory before reading any files.

### Rule 4: Follow Source Maps Directly

If a build artifact contains `//# sourceMappingURL=`, that is a direct pointer to the real source. Use it.

**FORBIDDEN**:
```
File: dist/app.bundle.js
Line: //# sourceMappingURL=app.bundle.js.map
Agent: *ignores source map, attempts to read minified bundle*
```

**REQUIRED**:
```
File: dist/app.bundle.js
Line: //# sourceMappingURL=app.bundle.js.map
Agent: Source map available. Reading app.bundle.js.map to resolve original source path.
       Original source: src/components/Auth.tsx line 47.
       Reading src/components/Auth.tsx instead.
```

### Rule 5: For Dependency Bugs, Fix the Call Site — Not the Dependency

When a bug originates inside `node_modules/` (an installed third-party package), the correct fix is almost always in *your code* — the call site, configuration, or version pin — not inside the package itself.

**FORBIDDEN**:
```
Stack trace shows bug in node_modules/axios/lib/core/Axios.js
Agent: *reads and attempts to patch node_modules/axios source*
```

**REQUIRED**:
```
Stack trace shows bug in node_modules/axios/lib/core/Axios.js
Agent: This is inside axios. My job is to find the call site in my code
       that is invoking axios incorrectly.
       *searches own codebase for axios usage*
       *reads axios documentation or type definitions for correct API*
       *fixes the call site in src/*
```

Exception: If you are a maintainer of the dependency and it is a workspace package, then navigating to its source is correct.

## Decision Tree

```
Encounter a file path during debugging
         │
         ▼
Is this file in dist/, build/, out/, .next/, node_modules/, or is it minified?
         │
    YES  │  NO
         │   └─→ Proceed with normal debugging
         ▼
Does a source map exist (sourceMappingURL)?
         │
    YES  │  NO
         │   └─→ Check for workspace config at repo root
         ▼         │
Follow source map  │  Is this a workspace/monorepo package?
to original file   │       │
                   │  YES  │  NO
                   │       │   └─→ Check for sibling src/ directory
                   │       ▼         │
                   │  Navigate to    │  YES → Debug in src/
                   │  workspace pkg  │  NO  → Fix your call site
                   │  source dir     │        (for node_modules)
                   └─────────────────┘
```

## Anti-Patterns to Avoid

| Anti-Pattern | Why It Fails | Correct Approach |
|--------------|-------------|------------------|
| Reading minified JS to understand logic | Minification removes readability; conclusions are unreliable | Follow source map or find source project |
| Searching for variable names in dist/ | Minification renames variables; search results are meaningless | Search in src/ of the originating project |
| Patching node_modules/ files | Changes are wiped on next install | Fix the call site or pin a different version |
| Assuming dist/ reflects current source | Build may be stale; dist can lag behind src/ changes | Always read src/ for current behavior |
| Debugging compiled TypeScript .js output | Type information lost; control flow obscured | Read the .ts source file instead |
| Treating build errors as source errors | Build errors often point to transpiler or config issues, not source logic | Read the source file named in the error, not the compiled output |

## Integration with Research Before Decision

This rule is a specialization of `research-before-decision` for the build-output disambiguation case:

- `research-before-decision` requires research before acting on any technical question
- `debug-source-not-output` specifies *where to research* when the trail leads into build artifacts

When a stack trace or error points into build output, the required research action is: **find the source**, not read the artifact.

## Platform Applicability

Applies universally across all AI coding platforms:
- Claude Code, Codex, Copilot, Cursor, Warp, Factory, OpenCode, Windsurf
- Any agent performing debugging, code review, error tracing, or stack trace analysis

## Checklist

Before analyzing any file encountered during debugging, verify:

- [ ] Is this file in a build output directory (`dist/`, `build/`, `out/`, `node_modules/`, `.next/`)?
- [ ] Does it contain minified or obfuscated code?
- [ ] Does it have a `sourceMappingURL` comment?
- [ ] Is there a workspace config at the repo root mapping this artifact to a source package?
- [ ] Is there a sibling `src/` directory in the same project?
- [ ] If inside `node_modules/`, is my call site the real problem?

If any answer is yes — navigate to source before reading the artifact.

## References

- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md - Parent rule: research before acting
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/thought-protocol.md - Research thought type
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/tao-loop.md - TAO loop standardization

---

**Rule Status**: ACTIVE
**Last Updated**: 2026-04-10