Using issuekit and testkit

Quick reference for using issuekit and testkit during issue implementation. Both tools are part of the Tom workspace toolchain.

---

Overview

Tool	Purpose	Detailed Docs
`issuekit`	Issue lifecycle management	issuekit_command_reference.md , issue_tracking.md
`testkit`	Test execution and tracking	test_tracking.md , tom_test_kit/test_tracking.md

---

Issue Implementation Flow

                                    ┌─────────────────┐
                                    │ User reports    │
                                    │ issue or        │
                                    │ Copilot creates │
                                    └────────┬────────┘
                                             │
       ┌───────────────────────────┬─────────┼─────────┬───────────────────────────┐
       │                           │         │         │                           │
       ▼                           ▼         ▼         ▼                           ▼
┌─────────────┐             ┌─────────────┐     ┌─────────────┐             ┌─────────────┐
│ :new        │             │ :analyze    │     │ :assign     │             │ :testing    │
│             │────────────►│             │────►│             │────────────►│             │
│ Create      │             │ Root cause  │     │ Project +   │             │ Test exists │
└─────────────┘             └─────────────┘     │ test entry  │             └──────┬──────┘
                                                └─────────────┘                    │
                                                                                   │
       ┌───────────────────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Developer / Copilot Work                                                │
│                                                                         │
│  :scan --missing-tests → Write test → Fix code → testkit :test         │
│                                                                         │
└────────────────────────────────────────────────────────┬────────────────┘
                                                         │
       ┌─────────────────────────────────────────────────┘
       │
       ▼                           ▼                           ▼
┌─────────────┐             ┌─────────────┐             ┌─────────────┐
│ :verify     │             │ :resolve    │             │ :close      │
│             │────────────►│             │────────────►│             │
│ Tests pass  │             │ Confirmed   │             │ Done        │
└─────────────┘             └─────────────┘             └─────────────┘

---

issuekit Commands

Creating and Triaging Issues

# Create a new issue
issuekit :new "Parser crashes on empty input" --severity high

# Analyze an issue (record root cause)
issuekit :analyze 42 --root-cause "Missing null check in tokenizer" --project tom_d4rt

# Assign to a project (creates test entry in tom_tests)
issuekit :assign 42 --project tom_d4rt --module parser

Finding Issues to Work On

# List new issues awaiting triage
issuekit :list --state new

# Find issues assigned to a project
issuekit :scan --project tom_d4rt

# Find issues with tests that haven't been written yet
issuekit :scan --missing-tests

Updating Issue State

# Mark that dart test exists (not just stub)
issuekit :testing 42

# All tests pass - ready for confirmation
issuekit :verify 42

# Reporter/reviewer confirms fix
issuekit :resolve 42

# Close the issue
issuekit :close 42

Regression Detection

# Sync state based on test results (detects regressions)
issuekit :sync

# Aggregate baselines from all projects
issuekit :aggregate

---

testkit Commands

Running Tests

# Run tests and add results to most recent baseline
testkit :test

# Run tests with comment label
testkit :test -c "after parser fix"

# Run specific tests
testkit :test --test-args="--name 'parser'"

Creating Baselines

# Create new baseline (captures current state)
testkit :baseline

# With comment
testkit :baseline -c "before refactor"

Analyzing Results

# Quick status summary
testkit :status

# What changed since baseline?
testkit :basediff

# What changed since last run?
testkit :lastdiff

# Track specific test over time
testkit :history D4-42-PAR-7

# Find flaky tests
testkit :flaky

Managing Tracking Files

# Keep only last N runs
testkit :trim 5

# Start fresh
testkit :reset

---

Test ID Convention

Tests use structured IDs that link to issues:

// Issue-linked test
test('D4-42-PAR-7: Parser crashes on empty input [2026-02-10 08:00] (FAIL)', () {
  // Test reproduces issue #42
});

// Regular test (no issue link)
test('D4-PAR-15: Parser handles nested objects [2026-01-15 10:00]', () {
  // Normal feature test
});

ID Format

Form	Format	Example	Use Case
Regular	`<PROJECT>-<project-specific>`	`D4-PAR-15`	Normal tests
Issue-linked	`<PROJECT>-<issue>-<project-specific>`	`D4-42-PAR-7`	Tests for issues
Stub	`<PROJECT>-<issue>`	`D4-42`	Placeholder before test written

Result Format

Each result cell: <result>/<expectation>

Cell	Meaning
`OK/OK`	Passed as expected (healthy)
`X/OK`	Failed unexpectedly (regression)
`X/X`	Failed as expected (known issue)
`OK/X`	Passed unexpectedly (potential fix)

---

Common Workflows

Workflow: Pick Up an Assigned Issue

# Find issues needing tests
issuekit :scan --missing-tests

# Found D4-42 needs a test → write the test
# File: test/parser_test.dart
test('D4-42-PAR-7: Parser crashes on empty input [2026-02-10 08:00] (FAIL)', () {
  final parser = Parser();
  expect(() => parser.parse(''), returnsNormally);
});

# Mark that test exists
issuekit :testing 42

# Run tests to confirm failure
testkit :test

Workflow: Fix and Verify

# Implement fix...

# Run tests to confirm fix
testkit :test

# If all pass, update issue state
issuekit :verify 42

# After confirmation
issuekit :resolve 42
issuekit :close 42

Workflow: Copilot Files Cross-Project Issue

# While working on tom_d4rt, discovered bug in tom_crypto
issuekit :new "Cipher fails on empty input" --severity high

# Later, in another session working on tom_crypto
issuekit :list --state new
issuekit :assign 103 --project tom_crypto --module cipher

---