codexkit 1.0.0

package/.codex/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
+version: 1.0.0
+tags: [debugging, workflow]
+dependencies: []
+---
+
+# Systematic Debugging
+
+> **Replaces** "shotgun debugging" — making random changes hoping something fixes the issue without understanding the cause
+
+## When to Use
+
+- Test failures, production bugs, build breaks, or unexpected behavior
+- Issues with unclear root cause or multiple failed fix attempts
+- Situations where time pressure makes “quick fixes” tempting
+
+## When NOT to Use
+
+- Pure feature development with no failures to investigate
+- Non-technical questions that don’t require root cause analysis
+
+## Debugging Checklist
+
+- [ ] Read error messages/stack traces fully
+- [ ] Reproduce consistently (or gather more data)
+- [ ] Check recent changes (diffs, deps, config)
+- [ ] Trace data flow to source (use root-cause-tracing if deep)
+- [ ] Form a single hypothesis and test minimally
+- [ ] Create a failing test before implementing the fix
+- [ ] Implement one change and verify it resolves the issue
+- [ ] If 3+ fixes fail, stop and question architecture
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Debug File Protocol
+
+**Persistent debugging state survives context resets:**
+
+**Location:** `.planning/debug/{slug}.md` or `.beads/artifacts/<id>/debug/{slug}.md`
+
+**Template:**
+
+```markdown
+# Debug: [Brief Issue Description]
+
+**Opened:** [Date]
+**Status:** [gathering | investigating | fixing | verifying | resolved]
+**Reporter:** [human partner or "self-detected"]
+
+## Symptoms
+
+- [ ] Symptom 1: [What happens / doesn't happen]
+- [ ] Symptom 2: [Additional observation]
+
+## Eliminated Hypotheses
+
+- [x] [Hypothesis]: [Why it was wrong] (date)
+
+## Evidence Log
+
+| Timestamp | Data                | Interpretation  |
+| --------- | ------------------- | --------------- |
+| [time]    | [What was observed] | [What it means] |
+
+## Current Hypothesis
+
+[I think X is happening because Y. Testing with Z.]
+
+## Fix Attempts
+
+| #   | Change             | Result      | Notes |
+| --- | ------------------ | ----------- | ----- |
+| 1   | [What was changed] | [Pass/Fail] | [Why] |
+
+## Resolution
+
+**Root Cause:** [What was actually wrong]
+**Fix:** [How it was fixed]
+**Date:** [When resolved]
+```
+
+**Update Rules:**
+
+- **OVERWRITE** when updating status or hypothesis
+- **APPEND** to Evidence Log and Fix Attempts
+
+**Status Transitions:**
+
+- `gathering` → `investigating` → `fixing` → `verifying` → `resolved`
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   **REQUIRED SUB-SKILL:** Use skill({ name: "root-cause-tracing" }) for backward tracing technique
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+**Evidence-Based Debugging (GSD Method):**
+
+**Information you have:**
+
+- ✅ Errors/warnings (with exact messages, line numbers)
+- ✅ Code I can read and trace through
+- ✅ Evidence from what I can observe directly
+
+**Information you DON'T have:**
+
+- ❌ What the user intended (ask if unclear)
+- ❌ Environment-specific state I can't observe
+- ❌ Intent behind code that doesn't match my understanding
+
+**When to gather more evidence vs. when to form hypothesis:**
+
+- **Gather evidence** when: Multiple components involved, unclear which one fails
+- **Form hypothesis** when: Error message points to specific location, pattern is clear
+- **Ask user** when: Behavior contradicts apparent code intent
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - **REQUIRED SUB-SKILL:** Load `$safe-implementation` for writing proper failing tests (RED phase)
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse                                       | Reality                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| "Issue is simple, don't need process"        | Simple issues have root causes too. Process is fast for simple bugs.    |
+| "Emergency, no time for process"             | Systematic debugging is FASTER than guess-and-check thrashing.          |
+| "Just try this first, then investigate"      | First fix sets the pattern. Do it right from the start.                 |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it.                       |
+| "Multiple fixes at once saves time"          | Can't isolate what worked. Causes new bugs.                             |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely.              |
+| "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause.                             |
+| "One more fix attempt" (after 2+ failures)   | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Changing multiple things at once | You can’t isolate what actually fixed or broke behavior | Change one variable at a time and measure outcome |
+| Not reading the error message carefully | You skip direct clues (file, line, code, failing invariant) | Read the full error and stack trace before edits |
+| Assuming the bug is in the most recently changed code | Correlation bias hides older or shared-state causes | Trace actual data/control flow from symptom to source |
+| Skipping reproduction steps | Non-repro bugs encourage guessing and untestable fixes | Establish reliable repro steps, then verify fix against them |
+
+## Quick Reference
+
+| Phase                 | Key Activities                                         | Success Criteria            |
+| --------------------- | ------------------------------------------------------ | --------------------------- |
+| **1. Root Cause**     | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY     |
+| **2. Pattern**        | Find working examples, compare                         | Identify differences        |
+| **3. Hypothesis**     | Form theory, test minimally                            | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify                               | Bug resolved, tests pass    |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Integration with Other Skills
+
+**This skill requires using:**
+
+- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
+- **safe-implementation** - REQUIRED for creating failing test case via TDD RED phase (see Phase 4, Step 1)
+
+**Complementary skills:**
+
+- **defense-in-depth** - Add validation at multiple layers after finding root cause
+- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
+- **verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common
+
+## Verification
+
+- Confirm the fix: reproduce the original bug scenario — it must now succeed.
+- Regression check: run related tests to ensure fix didn't break adjacent behavior.
+
+## See Also
+
+- **root-cause-tracing** - Deep call-stack tracing to identify original trigger before fixing
+- **condition-based-waiting** - Stabilize timing/race-condition fixes with state-based waits

package/.codex/skills/task-planning/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: task-planning
+description: Goal-backward planning workflow with dependency analysis, wave execution, and clear deliverables.
+---
+# task-planning
+
+## Purpose
+Convert a desired end state into executable tasks with explicit dependencies and parallel waves.
+
+## Use This Skill When
+- Breaking down complex tasks
+- Drafting implementation plans
+- Organizing multi-step delivery
+- Coordinating parallel contributors
+
+## Workflow Phases
+1. Define end state
+2. Work backward decomposition
+3. Dependency analysis
+4. Wave assignment
+
+## Expected Outputs
+- Task list with done criteria
+- Dependency graph (needs/creates)
+- Wave-by-wave execution plan
+- Verification gates and risk notes
+
+## Success Indicators
+- Every task has concrete artifacts and completion criteria
+- Dependencies are explicit and conflict-aware
+- Parallelism is used where safe
+- Each wave has checkpoint verification
+
+## Typical Plan Inputs
+- Goal statement and acceptance criteria
+- Constraints (tooling, runtime, release window)
+- Existing tests and quality gates
+- Ownership map for touched modules
+
+## Goal-Backward Method
+1. Write end state as measurable outcome.
+2. List evidence needed to claim done.
+3. Ask what must be true immediately before completion.
+4. Repeat until prerequisites are directly actionable.
+5. Convert prerequisites into scoped tasks.
+
+## Phase Detail
+
+### 1) Define End State
+- Write one testable end condition.
+- Declare non-goals to prevent scope creep.
+- Define required verification commands.
+
+Output: end-state statement + acceptance checklist.
+
+### 2) Work Backward Decomposition
+- Split outcome into milestones, then tasks.
+- Attach likely files and outputs to each task.
+- Keep tasks small enough for one focused session.
+
+Output: task list with IDs, files, done criteria.
+
+### 3) Dependency Analysis
+- Record `needs` and `creates` for each task.
+- Add edges where outputs are consumed downstream.
+- Mark same-file writes as sequential by default.
+
+Output: dependency graph with conflict notes.
+
+### 4) Wave Assignment
+- Wave 1: no dependencies.
+- Wave N: all dependencies in earlier waves.
+- Add checkpoint after each wave.
+
+Output: ordered wave plan with gate criteria.
+
+## Planning Data Model
+```yaml
+- id: T1
+  title: Add input schema
+  needs: []
+  creates: [validated-input]
+  files: [src/commands/init.ts]
+  verify: ["vitest src/commands/init.test.ts", "npm run typecheck"]
+  done_when: schema rejects invalid payload
+```
+
+## Dependency Rules
+- Same-file writes are sequential unless non-overlapping edits are guaranteed.
+- Contract/type outputs must be explicit artifacts.
+- High-risk tasks need mitigation or rollback note.
+- No task may depend on undocumented assumptions.
+
+## Wave Assignment Example
+### Objective
+Add `--dry-run` mode with tests and docs.
+
+### Task Graph
+- T1: parse `--dry-run`; creates parsed-flag
+- T2: add no-write runtime branch; needs parsed-flag
+- T3: unit tests for branch behavior; needs runtime-branch
+- T4: update help/docs; needs parsed-flag
+- T5: integration test for no filesystem writes; needs runtime-branch
+
+### Wave Plan
+- Wave 1: T1
+- Wave 2: T2, T4
+- Wave 3: T3, T5
+
+### Checkpoints
+- After Wave 1: parser tests
+- After Wave 2: typecheck + help-text verification
+- After Wave 3: full test + lint gates
+
+## Dependency Graph Example
+```text
+T1 -> T2 -> T3
+  \-> T4
+T2 -> T5
+```
+
+## Task Template
+```markdown
+### [T#] <title>
+- Goal:
+- Files:
+- Needs:
+- Creates:
+- Risks:
+- Verification:
+  - cmd 1
+  - cmd 2
+- Done when:
+```
+
+## Estimation Heuristics
+- S: single file, obvious change.
+- M: 2-3 files, one boundary crossing.
+- L: cross-module updates with integration risk.
+
+Confidence:
+- High: known approach exists.
+- Medium: approach known, edge cases unclear.
+- Low: architecture uncertainty/external coupling.
+
+## Common Planning Patterns
+### Vertical Slice First
+Build the thinnest end-to-end path first to de-risk assumptions.
+
+### Contract-First Parallelization
+Define shared interfaces first, then parallelize module work.
+
+### Risk Frontloading
+Schedule unknown/high-risk tasks in earliest wave.
+
+## Anti-Patterns
+| Anti-pattern | Symptom | Better move |
+|---|---|---|
+| One giant task | No progress visibility | Split by artifacts/dependencies |
+| Missing needs/creates | Hidden blockers | Require explicit edges |
+| Fully sequential plan | Slow throughput | Parallelize file-disjoint work |
+| Verification only at end | Late failures | Per-wave checkpoints |
+| Planning by directory only | Coupling missed | Plan by behavior/contracts |
+
+## Verification Gates for Plans
+- Gate 1: each task has files, verification, done criteria.
+- Gate 2: dependency edges justified; no cycles.
+- Gate 3: wave ordering valid; no unresolved prerequisites.
+
+## Plan Review Questions
+- Does each task create an artifact another task consumes?
+- Can any task be removed without harming end state?
+- Are high-risk unknowns scheduled early?
+- Is there an integration checkpoint before handoff?
+
+## Output Format
+```markdown
+## End State
+- measurable outcome
+
+## Non-goals
+- explicit exclusions
+
+## Task List
+- T1 ...
+- T2 ...
+
+## Dependency Graph
+- edge list or ASCII
+
+## Wave Plan
+- Wave 1: ...
+- Wave 2: ...
+
+## Verification Gates
+- per-wave commands
+
+## Risks
+- risk + mitigation + owner
+```
+
+## Exit Conditions
+- Another engineer can execute plan without reinterpretation.
+- Dependency graph and wave assignment are consistent.
+- Verification commands are specific and runnable.