tracer

Tracer: Iterative End-to-End Implementation

You are running the Tracer workflow -- a tracer bullet approach to feature implementation. Build the thinnest possible end-to-end path first, validate it works, then iteratively widen by adding one concern at a time. Feature: $ARGUMENTS

When to Use

• When integration risk is high (feature crosses multiple boundaries or systems)
• For vertical slices that span UI, API, service, and persistence layers
• When you want always-working increments instead of big-bang integration
• When the feature has unclear requirements but a clear happy path
• When parallelizing work (teammates can widen different passes simultaneously)

Overview

Tracer works in 6 phases. Each phase produces a working, committable increment.

Map the path (identify all layers/boundaries)
  -> Tracer (hardcoded happy path, no error handling)
    -> Widen: error handling (what breaks, how to recover)
      -> Widen: edge cases & validation (boundary conditions, replace hardcoded values)
        -> Widen: tests (verify all passes)
          -> Report (summary, gaps, remaining work)

---

Phase 1: Map the Path

1a. Clarify the Feature

If $ARGUMENTS is empty or too vague, ask one clarifying question about the trigger, expected outcome, or data flow. Do not over-question -- tracer discovers details through implementation, not upfront specification.

1b. Identify Layers and Boundaries

Read the project structure to identify every layer or boundary the feature must cross (UI, controller, service, data access, external systems, infrastructure). Use Glob and Read to discover where similar features are implemented and what patterns each layer follows.

1c. Create the Path Map

Produce a visual map showing each layer and what the tracer will touch:

## Path Map: [feature name]

**User action:** [e.g., "User clicks 'Export' button"]
**Expected outcome:** [e.g., "CSV file downloads with filtered data"]

**Layers to cross:**
1. **UI Component** (`src/components/Export.tsx`)
   - Add export button, wire click handler

2. **API Client** (`src/api/export.ts`)
   - Add exportData(filters) method

3. **API Endpoint** (`src/routes/export.ts`)
   - POST /api/export handler

4. **Service Layer** (`src/services/ExportService.ts`)
   - generateExport(userId, filters) method

5. **Data Access** (`src/repositories/DataRepository.ts`)
   - fetchRecords(userId, filters) query

6. **Database**
   - Query existing records table

**External boundaries:**
- [None | Third-party API | File storage | etc.]

**Existing patterns to follow:**
- [e.g., "Import feature at src/features/import/ shows full layer structure"]

---

Phase 2: Tracer (Happy Path)

2a. Implementation Strategy

Implement the absolute minimum at each layer to make one successful end-to-end request work. You think like a tunneler cutting through rock -- no error handling, no edge cases, no validation beyond null safety. Hard-code freely (test IDs, sample data, stubbed externals). Skip auth, logging, rate limiting. The only goal is proving the path exists.

2b. Implement Bottom-Up

Start at the deepest layer (database/external system) and work up to the UI so each layer has a working foundation. At each layer: match existing patterns, implement minimal code, verify it compiles.

2c. Verify End-to-End

Run the application and execute the happy path manually. If it fails, debug and fix before proceeding.

2d. Commit the Tracer

git add [files modified]
git commit -m "$(cat <<'EOF'
tracer: [feature name] happy path

Implemented thinnest end-to-end path across [N] layers.
- [Layer 1]: [what was added]
- [Layer 2]: [what was added]
...

Hard-coded: [list any hard-coded values to replace in Phase 4]
No error handling, validation, or tests yet.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

---

Phase 3: Widen — Error Handling

3a. Enumerate Failure Modes

For each layer, identify what can fail: connection loss, timeouts, invalid input, missing resources, permission denied, network failures, resource exhaustion.

3b. Implement Error Handling

You think like a defensive programmer adding safety nets to a working path. For each failure mode: detect it, recover or report clearly to the caller, and propagate appropriately (never swallow silently). Follow the project's existing error conventions (exceptions vs. Result types, logging patterns, error response format).

3c. Verify Error Paths

Simulate each failure (disconnect DB, mock failing API, send invalid input) and verify correct handling, appropriate user-facing messages, and graceful degradation (no crashes, no corrupt state).

3d. Commit Error Handling

git add [files modified]
git commit -m "$(cat <<'EOF'
tracer: [feature name] error handling

Added error handling at all layers:
- [Layer 1]: [what errors are handled]
- [Layer 2]: [what errors are handled]
...

Tested: [list failure scenarios verified]

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

---

Phase 4: Widen — Edge Cases & Validation

4a. Identify Edge Cases

You think like a tester probing boundaries: empty inputs, boundary values (zero, max, empty sets), duplicate/concurrent operations, large inputs, and special characters (unicode, injection vectors).

4b. Add Input Validation

At each layer's entry point, validate required fields, types/formats, ranges, and sanitize input. Return clear validation errors.

4c. Replace Hard-Coded Values

Replace all Phase 2 hard-coded values (test IDs, sample data, stubs) with real implementations -- parameters, configuration, or dynamic generation.

4d. Handle Edge Cases

Implement handling for each identified edge case and verify the behavior.

4e. Commit Edge Cases & Validation

git add [files modified]
git commit -m "$(cat <<'EOF'
tracer: [feature name] edge cases and validation

Added validation at all entry points:
- [Layer 1]: [what is validated]
- [Layer 2]: [what is validated]
...

Handled edge cases: [list]
Replaced hard-coded: [list]

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

---

Phase 5: Widen — Tests

Use the /test-strategy workflow to plan and execute this phase. It covers test level selection, coverage mapping, and execution order appropriate for the feature.

5a. Determine Test Coverage

Choose test levels appropriate for this feature (unit, integration, e2e). Follow project conventions. If the project has no tests, create at least basic integration tests for the core path.

5b. Write Tests

Match existing test style. Cover happy path (Phase 2), error scenarios (Phase 3), and edge cases (Phase 4) in priority order. Run tests, and if they fail, fix the implementation (not the tests).

5c. Commit Tests

git add [files modified]
git commit -m "$(cat <<'EOF'
tracer: [feature name] tests

Added [unit/integration/e2e] tests:
- Happy path: [coverage]
- Error handling: [coverage]
- Edge cases: [coverage]

Test results: [summary of test run]

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

---

Phase 6: Report

6a. Feature Summary

Produce a final report:

## Tracer Report: [feature name]

### Implementation Summary

**Passes completed:**
1. **Tracer (Happy Path)**: [date/commit] — Implemented end-to-end in [N] layers
2. **Error Handling**: [date/commit] — Added handling for [N] failure modes
3. **Edge Cases & Validation**: [date/commit] — Validated [N] conditions, handled [M] edge cases
4. **Tests**: [date/commit] — Added [N] tests covering [unit/integration/e2e]

**Layers modified:**
- [Layer 1]: [files changed, LOC added]
- [Layer 2]: [files changed, LOC added]
...

**Commits:**
- [commit hash]: tracer: [feature] happy path
- [commit hash]: tracer: [feature] error handling
- [commit hash]: tracer: [feature] edge cases and validation
- [commit hash]: tracer: [feature] tests

### Test Coverage

| Test Level | Count | Status |
|------------|-------|--------|
| Unit | N | ✓ Passing |
| Integration | M | ✓ Passing |
| E2E | K | ✓ Passing |

**Scenarios covered:**
- Happy path: ✓
- [Error scenario 1]: ✓
- [Error scenario 2]: ✓
- [Edge case 1]: ✓
- [Edge case 2]: ✓

### Remaining Work

**Out of scope (intentional):**
- [Feature/concern not addressed in this tracer]
- [Reason it was descoped]

**Follow-up tasks:**
- [Task that should happen next]
- [Task that depends on this feature]

**Known limitations:**
- [Limitation 1 and why it exists]
- [Limitation 2 and why it exists]

6b. Persist Architectural Insights to Domain Memory

After completing the report, extract architectural findings discovered during implementation and persist them to .claude/tackline/memory/project/domain.md.

What to extract — look for concepts that emerged during the tracer that are project-specific and would help a future session understand this codebase:

• Layer names or boundary names specific to this project (e.g., "the service layer means X here, not Y")
• Naming conventions or patterns that differ from common usage
• Architectural terms that have a specific meaning in this codebase
• Data flow or integration patterns that are non-obvious
• Constraints or invariants discovered during implementation

What NOT to extract:

• General programming concepts with standard meanings
• Findings that are only relevant to the specific feature implemented (not the broader codebase)
• Speculation — only persist what was confirmed by reading actual code

Format — for each extracted concept, use the domain format exactly:

## <Term>
**Definition**: <one sentence — what this term means in this project>
**Disambiguation**: <how this meaning differs from common use, if applicable — omit line if not ambiguous>
**Added**: YYYY-MM-DD

Process:

1. Read .claude/tackline/memory/project/domain.md if it exists. If it does not, create it with the header:

   # Project Domain Terminology
   
   Terms and disambiguation rules for this project. Maintained by `/domain`.
   
   ---
   
   

2. For each concept to persist:
   • Check if a ## <Term> heading already exists (case-insensitive). If it does, skip — do not duplicate.
   • If new, append the entry below the last entry in the file.
3. If no architectural insights were found worth persisting, skip this step entirely — do not write an empty or placeholder entry.
4. After writing, confirm in the report output: "Persisted N domain concepts to .claude/tackline/memory/project/domain.md." (or "No new domain concepts to persist." if none).

6c. Create Follow-Up Tasks

If follow-up work was identified:

Create follow-up tasks using your preferred task tracking approach. Each task should include the title, priority, and context from the tracer work. If no tracker is configured, write follow-up tasks to TODO.md in the project root.

---

Dispatch Mode

Standard mode (default): Run all phases directly in the current branch. Commits land on the working branch as the tracer progresses.

Worktree isolation mode: Dispatch the entire tracer workflow to a Task agent running in an isolated git worktree. All commits happen on a temporary branch. The user reviews the result and decides to merge or discard — clean abort at any phase means discarding the worktree with no revert needed.

Standard Mode (default)

Run /tracer <feature> with no special syntax. All phases execute in the current context and commit to the current branch.

Worktree Isolation Mode

Use when you want to keep the main branch clean until the full tracer is reviewed, or when integration risk is high enough that a clean discard path is valuable.

Dispatch:

Task({
  subagent_type: "general-purpose",
  isolation: "worktree",
  prompt: "Run the full Tracer workflow for: <feature>. Complete all phases (Map, Tracer, Error Handling, Edge Cases, Tests, Report) and commit each phase to this isolated worktree branch. Do not modify the main branch."
})

After the isolated agent completes:

1. Review the branch name returned in the Task result.
2. Inspect the commits: git log --oneline <branch>
3. Choose:
   • Merge: git merge <branch> or open a PR to bring the tracer into the main branch.
   • Discard: Delete the worktree branch. No revert needed — the main branch was never touched.

---

Guidelines

1. Compaction resilience: Per rules/memory-layout.md, checkpoint at phase boundaries to .claude/tackline/memory/scratch/tracer-checkpoint.md.
2. Each phase produces a working increment. Never proceed to the next phase if the current one is broken.
3. Commit after every phase. Commits provide rollback points and document the tracer's progression.
4. Hard-coding in Phase 2 is expected. The point is to prove the path, not build production code immediately.
5. Bottom-up implementation reduces risk. Each layer has a working foundation when you build on it.
6. Phase order is flexible. If tests before error handling makes more sense for the feature, reorder accordingly.
7. Verify after every widening pass. Run the feature manually after Phases 3, 4, and 5 to ensure nothing broke.
8. Stop at any phase. If the session ends early, you have working code at the last committed phase.
9. Widen one concern at a time. Don't mix error handling and validation in the same pass -- each pass is focused.
10. Follow project conventions. Match existing patterns for error handling, validation, testing, and file organization.
11. Create tasks for follow-up work. If scope is cut or limitations are discovered, document them in your task tracker (or in TODO.md if no tracker is configured).

See Also

• /test-strategy — test level selection, coverage mapping, and execution planning (used in Phase 5)
• /spec — formalize requirements before starting the tracer when the feature is ambiguous
• /premortem — identify failure modes before Phase 2 on high-risk integrations
• /review — code review of the completed tracer implementation