issue-tdd

name	issue-tdd
description	Investigate and fix a GitHub issue using Ard's preferred TDD workflow. Use when asked to work on, investigate, fix, or create a branch/PR for a GitHub issue or bug report.

Issue TDD Workflow

Use this workflow for Ard bug fixes and issue-driven implementation.

1. Read and summarize the issue

• Read the GitHub issue or linked local note completely.
• Identify:
  • expected behavior
  • observed behavior
  • minimal repro shape
  • affected layer: parser, checker, AIR, Go backend, formatter, LSP, etc.
• Restate the suspected failure mode briefly before editing.

2. Triage by reproducing

Prefer a regression test over an ad-hoc sample.

• Add the smallest failing test in the most specific package:
  • parser syntax: compiler/parse
  • type checking / semantic diagnostics: compiler/checker
  • AIR shape: compiler/air
  • Go output/runtime behavior: compiler/go
  • formatting: compiler/formatter
• Run only the new test first and confirm it fails for the expected reason.
• If a sample project is needed, create it in a temp dir and keep the command/output for the report.
• Do not proceed to implementation until the failure is reproduced.

3. Evaluate solutions

Before coding the fix, compare at least two plausible approaches when the solution is not obvious.

For each option, note:

• scope of change
• correctness/generalization
• regression risk
• compatibility with existing architecture

Prefer the smallest correct fix, but record larger architectural follow-ups as GitHub issues when appropriate.

4. Implement using TDD

• Make the failing test pass with a focused change.
• Avoid broad rewrites unless the issue requires one.
• Keep diagnostics explicit; do not silently drop errors.
• Preserve existing behavior unless the issue requires changing it.

5. Validate

Run targeted tests first, then broader tests as practical.

Typical commands from compiler/:

go test ./<package> -run <NewTestName> -count=1
go test ./parse ./checker ./air ./go -run '<relevant-pattern>' -count=1
go test ./... -count=1

If full test output exceeds the terminal timeout but package results are visible, report that accurately.

6. Report and handoff

Before committing, summarize:

• reproduction test added
• root cause
• chosen solution and rejected alternatives
• validation commands/results
• any untracked local repro notes not included

Only commit/push/create PR when explicitly asked. Use the commit-format skill before committing.