@ai-content-space/loopx 0.1.1 → 0.1.3

package/skills/clarify/SKILL.md

@@ -38,10 +38,12 @@ Most implementation drift happens before coding begins. Teams often think they n
 
 <Core_Principles>
 - Ask one question at a time.
+- Prefer bounded multiple-choice questions when the option space is known; use open-ended questions only when the option space is genuinely unknown.
 - Prefer the highest-leverage unresolved question, not broad coverage.
 - Keep digging on the same thread until one assumption, one boundary, or one tradeoff becomes clearer.
 - Treat every answer as a claim to pressure-test, not a final truth to copy down.
 - Make `Non-goals` and `Decision Boundaries` mandatory gates.
+- Default to YAGNI: shrink speculative scope unless the user gives a concrete reason it belongs in the first pass.
 - Do not stop at “requirements”; shape the solution enough that the next stage has a coherent starting design.
 </Core_Principles>
 
@@ -80,10 +82,20 @@ Do not mark a clarify spec handoff-ready by prose alone. Update the frontmatter
 </Runtime_State_Machine>
 
 <Execution_Policy>
+- Always run a preflight context intake before the first interview question.
+- If supplied context is too large for safe prompt use, first request or create a concise prompt-safe summary that preserves goals, constraints, success criteria, non-goals, decision boundaries, and source references.
 - Explore repo context before asking the user about internals.
 - Prefer evidence-backed clarification in brownfield work:
   - “I found X in Y. Should this clarify spec preserve that pattern?”
+- Route facts before judgment:
+  - discoverable codebase facts should be inspected directly
+  - evidence-backed inferences should be confirmed with the user
+  - product intent, tradeoffs, scope, non-goals, and decision boundaries must be treated as human decisions
 - Ask about intent and boundaries before implementation detail.
+- Respect stage priority:
+  1. intent, outcome, scope, non-goals, decision boundaries
+  2. constraints and success criteria
+  3. brownfield grounding and integration details
 - Stay on the same thread when the answer is still weak instead of rotating dimensions just for coverage.
 - Revisit at least one earlier answer with an explicit assumption, evidence, or tradeoff follow-up before crystallizing.
 - If the task is too large for one coherent spec, decompose it before pretending it is ready.
@@ -111,6 +123,45 @@ When an answer is still weak, prefer one of these next:
 4. If the answer is still describing symptoms, reframe toward root cause.
 </Pressure_Patterns>
 
+<Socratic_Questioning>
+`clarify` should be Socratic without being vague.
+
+- Ask one focused round at a time.
+- Prefer bounded choices when they reduce user effort:
+  - use single-choice when one answer should drive the next branch
+  - use multi-choice when several constraints, non-goals, or success checks may all apply
+  - include `Other` only when the known options are likely incomplete
+- Lead with the recommended option when repo evidence or prior answers support it, but make the tradeoff visible.
+- Do not hide a branching interview tree inside one overloaded question. If an option would require a follow-up, ask that follow-up next.
+- After each answer, decide whether the next highest-value move is:
+  - deeper pressure on the same thread
+  - zooming out to another unresolved breadth track
+  - crystallizing the spec
+</Socratic_Questioning>
+
+<Breadth_Ledger>
+Maintain a lightweight breadth ledger across independent ambiguity tracks:
+
+- scope
+- constraints
+- outputs / deliverables
+- verification and success criteria
+- brownfield integration
+- user-mentioned workstreams or stakeholder requirements
+
+The ledger is a guard, not a rotation rule. Stay deep on the current thread until it has been pressure-tested, then zoom out only when another material track remains unresolved and would change downstream execution.
+</Breadth_Ledger>
+
+<Challenge_Modes>
+Use these assumption stress tests when applicable:
+
+- **Contrarian**: challenge a core assumption when an answer rests on an untested belief.
+- **Simplifier**: probe the smallest viable first pass when scope expands faster than outcome clarity.
+- **Ontologist**: reframe toward essence/root cause when the user keeps describing symptoms or when ambiguity stalls.
+
+Track which challenge modes have been used in the ambiguity register. Do not repeat a mode mechanically.
+</Challenge_Modes>
+
 <Design_Shaping>
 `clarify` should not stop at “what do you want?” Once the intent is understandable, it should also shape the task enough that the downstream plan is not starting from zero.
 
@@ -120,10 +171,51 @@ When there is a real design choice:
 - lead with the recommended one
 - explain tradeoffs briefly
 - right-size the design to the task
+- identify likely component boundaries, data flow, or user-facing flow when that would materially affect planning
+- reject speculative features unless they are necessary for the stated outcome
 
 The goal is not to produce a full architecture doc here. The goal is to make the clarify spec design-ready.
 </Design_Shaping>
 
+<Incremental_Validation>
+For non-trivial designs, validate the design in small sections before writing the final clarify spec.
+
+Present a compact design summary and ask whether it matches the user's intent. When relevant, validate these sections separately:
+
+- user-facing behavior or workflow
+- component boundaries / ownership
+- data flow or API contract
+- error handling and edge cases
+- test and verification shape
+- explicitly deferred work
+
+If the user rejects a section, continue the interview loop instead of writing a handoff-ready spec.
+</Incremental_Validation>
+
+<Practical_Closure_Audit>
+Treat a low ambiguity score as permission to audit closure, not as automatic permission to stop.
+
+Before crystallizing, ask:
+
+- Would one more question materially change implementation, test strategy, or scope?
+- Are non-goals and decision boundaries explicit enough for downstream agents?
+- Has at least one assumption or tradeoff been pressure-tested?
+- Is remaining uncertainty residual risk rather than actionable ambiguity?
+
+If remaining uncertainty would not change execution, crystallize the spec and preserve it as residual risk instead of opening a low-value branch.
+</Practical_Closure_Audit>
+
+<Spec_Self_Review>
+Before marking a clarify spec handoff-ready, perform a self-review pass:
+
+- remove placeholders such as `TBD`, `TODO`, `REPLACE_ME`, or vague “etc.”
+- check for internal contradictions
+- check whether the scope is still too broad for one coherent execution package
+- check whether any requirement can be interpreted two materially different ways
+- verify that non-goals, decision boundaries, acceptance criteria, and residual risks are explicit
+- verify that brownfield evidence is labeled separately from inference
+</Spec_Self_Review>
+
 <Process>
 
 ## 1. Explore Context
@@ -131,12 +223,22 @@ The goal is not to produce a full architecture doc here. The goal is to make the
 - Read relevant files, docs, and current patterns first.
 - Classify the work as brownfield or greenfield.
 - For brownfield work, collect concrete evidence before questioning.
+- Create or update a compact context snapshot for the task when the conversation, source docs, or repo evidence would otherwise be too large to carry safely.
 
 ## 2. Interview
 
 - Ask one question per round.
+- Prefer bounded choices for known option spaces; use open-ended questions only when the valid answers cannot be enumerated.
+- Before asking each question, show a compact status line with:
+  - `round`: current round and max rounds
+  - `ambiguity_score`: current score
+  - `target`: selected profile threshold
+  - `open_items`: unresolved ambiguity count
+- Also state the current focus dimension and whether the round is fact confirmation or human judgment.
+- After the user answers and the round is updated, show the revised `ambiguity_score`, whether it moved up/down/unchanged, and the main reason for that change before asking the next question.
 - After each answered round, update `current_round`, the ambiguity register, and `ambiguity_score`.
-- Target the weakest unresolved dimension.
+- Target the weakest unresolved dimension within the stage-priority order.
+- Maintain the breadth ledger; do not rotate dimensions just for coverage.
 - Keep `Non-goals` and `Decision Boundaries` explicit from early in the process.
 - Respect the selected profile:
   - `standard`: stop only when the clarify spec is handoff-ready or `15` rounds are exhausted
@@ -154,6 +256,13 @@ The goal is not to produce a full architecture doc here. The goal is to make the
 - Where needed, propose a small set of options.
 - Recommend one approach.
 - Clarify what that approach implies for scope and downstream execution.
+- Apply incremental validation for non-trivial designs before finalizing the spec.
+
+## 4.5. Closure and Self-Review
+
+- Run the practical closure audit.
+- Run the spec self-review checklist before marking handoff-ready.
+- If the round cap is reached or the user chooses to proceed despite ambiguity, preserve an explicit residual-risk warning in the spec and handoff recommendation.
 
 ## 5. Write the Clarify Spec
 
@@ -179,8 +288,11 @@ The clarify spec should include:
 - constraints
 - success criteria
 - assumptions exposed and resolved
+- pressure-pass findings
 - brownfield evidence vs inference
+- breadth ledger / unresolved tracks, if any
 - design direction / preferred approach
+- residual risks
 - explicit next handoff recommendation
 
 ## 6. Handoff
@@ -191,6 +303,12 @@ After the clarify spec is ready:
 - hand off to `build` only if the user explicitly wants direct execution and the task is already concrete enough
 - hand off to `autopilot` only when the scope is sufficiently tight for a bounded end-to-end run
 
+Preferred explicit handoff contract:
+
+- Recommended invocation: `$plan <slug>`
+- Artifact-pinned invocation when needed: `$plan --direct .loopx/specs/clarify-<slug>-<timestamp>.md`
+- Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
+
 `clarify` itself does not implement the feature.
 
 </Process>
@@ -199,6 +317,8 @@ After the clarify spec is ready:
 - `Non-goals` are explicit
 - `Decision Boundaries` are explicit
 - At least one pressure-pass follow-up has revisited an earlier answer
+- The practical closure audit has passed
+- The spec self-review pass has removed placeholders, contradictions, and material ambiguity
 - A written clarify spec exists
 - The task is small enough and clear enough for real downstream handoff
 - The selected profile threshold is met:

package/skills/debug/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: debug
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## 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.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### 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:**
+
+   See `root-cause-tracing.md` in this directory for the complete 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?
+
+### 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
+   - Use the `tdd` skill for writing proper failing tests
+
+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. |
+
+## 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.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **tdd** - For creating failing test case (Phase 4, Step 1)
+- **verify** - 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

package/skills/debug/condition-based-waiting.md

@@ -0,0 +1,115 @@
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+
+**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**Use when:**
+- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
+- Tests are flaky (pass sometimes, fail under load)
+- Tests timeout when run in parallel
+- Waiting for async operations to complete
+
+**Don't use when:**
+- Testing actual timing behavior (debounce, throttle intervals)
+- Always document WHY if using arbitrary timeout
+
+## Core Pattern
+
+```typescript
+// ❌ BEFORE: Guessing at timing
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ AFTER: Waiting for condition
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## Quick Patterns
+
+| Scenario | Pattern |
+|----------|---------|
+| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| Wait for state | `waitFor(() => machine.state === 'ready')` |
+| Wait for count | `waitFor(() => items.length >= 5)` |
+| Wait for file | `waitFor(() => fs.existsSync(path))` |
+| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
+
+## Implementation
+
+Generic polling function:
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+
+## Common Mistakes
+
+**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
+**✅ Fix:** Poll every 10ms
+
+**❌ No timeout:** Loop forever if condition never met
+**✅ Fix:** Always include timeout with clear error
+
+**❌ Stale data:** Cache state before loop
+**✅ Fix:** Call getter inside loop for fresh data
+
+## When Arbitrary Timeout IS Correct
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**Requirements:**
+1. First wait for triggering condition
+2. Based on known timing (not guessing)
+3. Comment explaining WHY
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Fixed 15 flaky tests across 3 files
+- Pass rate: 60% → 100%
+- Execution time: 40% faster
+- No more race conditions