development

Overview

This skill provides comprehensive guidance on development practices, code quality standards, and the proper approach to handling incomplete work during implementation.

Core Principles:

• Completeness over speed - Never leave TODO markers or stub implementations
• Design before code - Every TODO discovered requires technical design first
• Type-driven development - Types are not optional, they are the contract
• No technical debt - Address issues immediately, don't defer them

---

🚨 CRITICAL: TODO Markers Are FORBIDDEN

The Hard Rule

TODO/FIXME/XXX/HACK markers in committed code are UNACCEPTABLE.

When you discover a TODO marker (whether you created it or inherited it), this is NOT a reminder for later work. This is a BLOCKING SIGNAL that:

1. ✅ There is incomplete design work
2. ✅ There is missing implementation
3. ✅ The code is broken or insufficient
4. ✅ You must stop and address it NOW

Why TODO Markers Are Problematic

// ❌ WRONG - This is a broken contract
export type StripTags<T extends string> = T;  // TODO: implement actual stripping

// ❌ WRONG - This defeats the purpose of the function
export function parseComplexData(input: string): ParsedResult {
    // TODO: implement proper parsing
    return {} as ParsedResult;
}

// ❌ WRONG - This is technical debt from day one
export function validateConfig(config: unknown): boolean {
    // FIXME: add validation logic
    return true;
}

Problems with the above:

1. Broken contracts - Users expect StripTags to strip tags, but it doesn't
2. Type lies - Return types promise something the implementation doesn't deliver
3. Hidden bugs - Code appears to work but fails in production
4. Compounding debt - One TODO leads to workarounds that create more TODOs
5. Lost context - Future you won't remember why the TODO exists or what it needs

---

The Proper Workflow When You Encounter a TODO

When you find a TODO marker (in existing code or while planning new code), follow this workflow:

Step 1: STOP Immediately

Do not proceed with any other work. TODOs are blocking issues.

# Immediately search for ALL TODOs in the affected area
rg -i "TODO|FIXME|XXX|HACK" modules/lib/src/

# Document what you found
echo "Found TODO in X: <description>" >> .ai/logs/current-phase.md

Step 2: Understand the Context

Ask yourself:

1. What is this TODO supposed to do?

   • Read the surrounding code
   • Check the function signature / type definition
   • Look at how it's being used
   • Review any related documentation

2. Why was it left incomplete?

   • Was it a lack of knowledge?
   • Was it complexity avoidance?
   • Was it a placeholder during design?
   • Was it genuinely forgotten?

3. What would a complete implementation look like?

   • What are the inputs and outputs?
   • What edge cases need handling?
   • What type-level computation is needed?
   • What tests would verify correctness?

Step 3: Technical Design

BEFORE writing any code, create a technical design for the complete solution.

For Type Utilities:

// DESIGN NOTES for StripSimpleTags<T>

/**
 * Goal: Remove all SimpleTag markup from a string literal type
 *
 * Input: "Hello <soft>world</soft> and <loud>universe</loud>"
 * Output: "Hello world and universe"
 *
 * Approach:
 * 1. Use recursive conditional types with template literals
 * 2. Pattern match each tag type: <soft>, </soft>, <loud>, </loud>, etc.
 * 3. For each match: extract before/after, strip tag, recurse
 * 4. Base case: no more tags found, return string as-is
 *
 * Edge Cases:
 * - Nested tags: <soft><loud>text</loud></soft>
 * - Multiple tags: <soft>a</soft> <loud>b</loud>
 * - No tags: "plain text"
 * - Empty string: ""
 * - Unclosed tags: <soft>text (treat as-is? or error?)
 *
 * Type Complexity: Medium (recursive template literals)
 * Estimated LOC: ~30-50 lines
 */

For Runtime Functions:

// DESIGN NOTES for parseComplexData()

/**
 * Goal: Parse structured data from string input
 *
 * Input Format: "key1=value1,key2=value2"
 * Output Format: { key1: string, key2: string }
 *
 * Algorithm:
 * 1. Split by commas to get key-value pairs
 * 2. Split each pair by '=' to separate key/value
 * 3. Trim whitespace from keys and values
 * 4. Build result object
 *
 * Edge Cases:
 * - Empty string: return {}
 * - Missing '=': throw error or skip?
 * - Duplicate keys: last wins or error?
 * - Special characters in values: escape handling?
 *
 * Error Handling:
 * - Invalid format: throw ParseError
 * - Malformed pairs: skip with warning or fail fast?
 *
 * Tests Needed:
 * - Happy path: valid input → correct output
 * - Empty input: "" → {}
 * - Malformed: "key1value1" → error
 * - Duplicates: "a=1,a=2" → {a: "2"}
 *
 * Estimated LOC: ~20-30 lines + error handling
 */

Step 4: Add to TODO List

Track this as a blocking task in your active todo list:

TodoWrite({
    todos: [
        // ... existing todos
        {
            content: "Implement StripSimpleTags type utility with recursive template literal parsing",
            activeForm: "Implementing StripSimpleTags type utility",
            status: "in_progress"
        },
        {
            content: "Add comprehensive type tests for StripSimpleTags",
            activeForm: "Adding type tests for StripSimpleTags",
            status: "pending"
        }
    ]
});

Step 5: Implement Completely

Implement the full, complete solution - no shortcuts, no new TODOs.

For Type Utilities:

/**
 * Strips all SimpleTag markup from a string literal type
 *
 * Handles: <soft>, </soft>, <loud>, </loud>, <fast>, </fast>, <slow>, </slow>
 */
export type StripSimpleTags<T extends string> =
    // Match <soft> opening tag
    T extends `${infer Before}<soft>${infer After}`
        ? StripSimpleTags<`${Before}${StripSimpleTags<After>}`>
    // Match </soft> closing tag
    : T extends `${infer Before}</soft>${infer After}`
        ? StripSimpleTags<`${Before}${StripSimpleTags<After>}`>
    // Match <loud> opening tag
    : T extends `${infer Before}<loud>${infer After}`
        ? StripSimpleTags<`${Before}${StripSimpleTags<After>}`>
    // Match </loud> closing tag
    : T extends `${infer Before}</loud>${infer After}`
        ? StripSimpleTags<`${Before}${StripSimpleTags<After>}`>
    // ... continue for all SimpleTags
    // Base case: no more tags
    : T;

For Runtime Functions:

export function parseComplexData(input: string): ParsedResult {
    if (!input || input.trim() === "") {
        return {};
    }

    const pairs = input.split(",");
    const result: Record<string, string> = {};

    for (const pair of pairs) {
        const [key, value] = pair.split("=");

        if (!key || !value) {
            throw new ParseError(`Invalid key-value pair: "${pair}"`);
        }

        result[key.trim()] = value.trim();
    }

    return result;
}

Step 6: Add Tests

Tests are not optional. Every implementation needs verification.

For Type Utilities:

describe("StripSimpleTags<T>", () => {
    it("should strip <soft> tags", () => {
        type Test1 = StripSimpleTags<"<soft>hello</soft>">;
        type Test2 = StripSimpleTags<"world <soft>hello</soft> universe">;

        type cases = [
            Expect<AssertEqual<Test1, "hello">>,
            Expect<AssertEqual<Test2, "world hello universe">>
        ];
    });

    it("should handle nested tags", () => {
        type Test = StripSimpleTags<"<soft><loud>hello</loud></soft>">;

        type cases = [
            Expect<AssertEqual<Test, "hello">>
        ];
    });

    it("should handle no tags", () => {
        type Test = StripSimpleTags<"hello world">;

        type cases = [
            Expect<AssertEqual<Test, "hello world">>
        ];
    });

    it("should handle empty string", () => {
        type Test = StripSimpleTags<"">;

        type cases = [
            Expect<AssertEqual<Test, "">>
        ];
    });
});

For Runtime Functions:

describe("parseComplexData()", () => {
    it("should parse valid input", () => {
        const result = parseComplexData("key1=value1,key2=value2");

        expect(result).toEqual({
            key1: "value1",
            key2: "value2"
        });
    });

    it("should handle empty string", () => {
        const result = parseComplexData("");

        expect(result).toEqual({});
    });

    it("should throw on invalid format", () => {
        expect(() => parseComplexData("invalid")).toThrow(ParseError);
    });

    it("should handle duplicate keys (last wins)", () => {
        const result = parseComplexData("key=first,key=second");

        expect(result).toEqual({ key: "second" });
    });
});

Step 7: Verify and Mark Complete

Only after implementation + tests both pass:

# Run tests
pnpm test
pnpm test:types

# Verify no TODOs remain in the affected files
rg -i "TODO|FIXME" path/to/file.ts

# Update todo list
TodoWrite({ todos: [...] })  # Mark as completed

---

Common Scenarios and Solutions

Scenario 1: "I don't know how to implement this"

❌ WRONG Response:

// TODO: Figure out how to implement this later
export function complexAlgorithm(): Result {
    return {} as Result;
}

✅ CORRECT Response:

1. Research first - Look for similar implementations in codebase or libraries
2. Ask for help - Use documentation, search GitHub, ask the user
3. Break it down - Decompose into smaller, manageable pieces
4. Prototype - Try a simple version first, then refine
5. Document - Write design notes explaining your approach

Scenario 2: "This is too complex for right now"

❌ WRONG Response:

// TODO: Optimize this later, current impl is slow
export function slowFunction(): void {
    // naive implementation
}

✅ CORRECT Response:

1. Implement it properly first - Even if not optimal, make it correct
2. Add performance tests - Measure actual impact before optimizing
3. Document tradeoffs - Explain why simple approach was chosen
4. No TODO - If it works correctly, it's complete

/**
 * Processes data using naive O(n²) algorithm
 *
 * NOTE: For datasets < 1000 items, performance is acceptable.
 * If profiling shows this is a bottleneck, consider:
 * - Hash table approach: O(n)
 * - Binary search: O(n log n)
 *
 * Current implementation prioritizes correctness and readability.
 */
export function processData(items: Item[]): Result {
    // correct implementation
}

Scenario 3: "This needs a major refactor"

❌ WRONG Response:

// FIXME: This whole module needs refactoring
export class LegacyClass {
    // messy code
}

✅ CORRECT Response:

1. File an issue - Document the refactor need in issue tracker
2. Make it work - Ensure current code is correct, even if messy
3. Plan the refactor - Create a separate refactor plan
4. No FIXME - Working code doesn't get TODO markers

/**
 * LegacyClass - Provides X functionality
 *
 * NOTE: This class has grown complex. See issue #123 for refactor plan.
 * Despite complexity, all public methods are tested and working correctly.
 */
export class LegacyClass {
    // working implementation
}

---

Type Utility Development Guidelines

The Type Utility Contract

When you write a type utility, you're making a compile-time promise to users:

// This signature is a CONTRACT
export type ParseJSON<T extends string> = /* ... */;

// Users expect:
// - Input: JSON string literal
// - Output: Typed object matching the JSON structure
// - Edge cases: Invalid JSON → never or error type

Red Flags for Incomplete Type Utilities

// ❌ Pass-through (does nothing)
export type MyUtility<T> = T;

// ❌ Always returns same type
export type HasProperty<T, K> = false;

// ❌ Uses 'any' as cop-out
export type ParseSomething<T> = any;

// ❌ TODO marker
// TODO: implement this
export type Incomplete<T> = T;

Proper Type Utility Implementation

// ✅ Does actual type-level computation
export type StrictExtract<T, U> = T extends U ? T : never;

// ✅ Uses conditional types correctly
export type IsArray<T> = T extends readonly unknown[] ? true : false;

// ✅ Complex but complete
export type DeepReadonly<T> = {
    readonly [K in keyof T]: T[K] extends object
        ? DeepReadonly<T[K]>
        : T[K]
};

---

Runtime Implementation Guidelines

The Function Contract

When you write a function signature, you're making a runtime promise:

// This signature is a CONTRACT
export async function fetchUser(id: number): Promise<User>;

// Users expect:
// - Input: valid number
// - Output: Promise that resolves to User object
// - Errors: Rejects on failure (network, not found, etc.)
// - Side effects: Documented (API call)

Red Flags for Incomplete Functions

// ❌ Returns mock/fake data
export function getRealData(): Data {
    return { fake: "data" } as Data;
}

// ❌ No implementation
export function complexCalculation(): number {
    return 0; // TODO: implement
}

// ❌ Catches and hides errors
export function dangerousOperation(): void {
    try {
        // something
    } catch {
        // TODO: proper error handling
    }
}

Proper Function Implementation

// ✅ Complete implementation
export async function fetchUser(id: number): Promise<User> {
    if (!Number.isInteger(id) || id <= 0) {
        throw new ValidationError("User ID must be positive integer");
    }

    try {
        const response = await fetch(`/api/users/${id}`);

        if (!response.ok) {
            throw new ApiError(`Failed to fetch user: ${response.status}`);
        }

        const data = await response.json();
        return validateUser(data);
    } catch (error) {
        if (error instanceof ApiError || error instanceof ValidationError) {
            throw error;
        }
        throw new NetworkError("Failed to connect to API", { cause: error });
    }
}

---

Quality Checklist

Before committing any code, verify:

Type Quality

• No TODO/FIXME/XXX/HACK markers
• No pass-through type utilities (unless intentional)
• All type utilities have meaningful implementations
• Complex types have JSDoc explaining the approach
• Type tests verify the utility works correctly
• Edge cases are handled (never, unknown, etc.)

Runtime Quality

• No TODO/FIXME/XXX/HACK markers
• All functions have complete implementations
• Error cases are handled explicitly
• Edge cases have tests
• Function signatures match implementation behavior
• No return type assertions (as Type) masking incomplete code

Testing Quality

• Runtime tests cover happy path + edge cases + errors
• Type tests verify type inference and narrowing
• Tests are deterministic (no flaky tests)
• All tests pass: pnpm test && pnpm test:types

---

When You're Stuck

If you genuinely can't complete something:

1. Don't Leave a TODO

❌ WRONG:

// TODO: implement this
export function incomplete(): void {}

2. Implement a Minimal Version

✅ CORRECT:

/**
 * Validates input data
 *
 * CURRENT: Basic validation checking required fields
 * FUTURE: Could be enhanced with schema validation, custom rules, etc.
 *
 * See issue #456 for enhancement ideas
 */
export function validateInput(input: unknown): ValidationResult {
    // Simple but COMPLETE implementation
    if (!input || typeof input !== "object") {
        return { valid: false, errors: ["Input must be an object"] };
    }

    return { valid: true, errors: [] };
}

3. Ask for Help

In your message to the user:

"I'm implementing X and need guidance on Y. I've researched Z and found A and B as potential approaches. Which direction should I take?"

NOT:

"I'll add a TODO and come back to this later."

---

Summary

The Golden Rule: No TODOs in Committed Code

Every TODO marker represents:

• ✅ Incomplete design work → Do the design now
• ✅ Missing implementation → Implement it now
• ✅ Insufficient knowledge → Research/ask now
• ✅ Deferred technical debt → Address it now

When you find a TODO:

1. STOP - Don't proceed with other work
2. DESIGN - Write technical design notes
3. TRACK - Add to todo list as blocking task
4. IMPLEMENT - Write complete solution
5. TEST - Verify it works
6. VERIFY - Confirm no TODOs remain

A phase with unresolved TODOs is an INCOMPLETE phase.

---

Quick Reference

# Search for TODOs before committing
rg -i "TODO|FIXME|XXX|HACK" modules/lib/src/

# Search specific areas
rg -i "TODO" modules/lib/src/types/
rg -i "FIXME" modules/lib/src/utils/

# Verify implementation completeness
rg "export type.*= T;$"  # Find pass-through types
rg "return.*as.*;"        # Find type assertions (often masking incomplete code)
rg "throw new Error\(\"Not implemented\"\)"  # Find stub functions