Skip to content

notque/vexjoy-agent / skills/process/workflow

workflow

Verified

Structured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.

FileKindSize
SKILL.mdskill md12.3 KB
references/adr-template.mdmarkdown9.4 KB
references/agent-upgrade.mdmarkdown12.2 KB
references/article-evaluation-pipeline.mdmarkdown8.9 KB
references/article-evaluation-pipeline/references/report-template.mdmarkdown2.5 KB
references/article-evaluation-pipeline/references/wabi-sabi-classification.mdmarkdown2.4 KB
references/auto-pipeline.mdmarkdown12.5 KB
references/auto-pipeline/references/pipeline-catalog.jsonconfig15.0 KB
references/auto-pipeline/references/pipeline-catalog.mdmarkdown4.3 KB
references/build_dag.pyscript12.5 KB
references/chain-composer.mdmarkdown19.8 KB
references/chain-composer/references/canonical-chains.mdmarkdown13.9 KB
references/comprehensive-review-workflow.jsscript19.1 KB
references/comprehensive-review.mdmarkdown27.4 KB
references/comprehensive-review/references/output-templates.mdmarkdown10.6 KB
references/comprehensive-review/references/wave-0-per-package.mdmarkdown5.1 KB
references/comprehensive-review/references/wave-1-foundation.mdmarkdown9.4 KB
references/comprehensive-review/references/wave-2-deep-dive.mdmarkdown6.7 KB
references/comprehensive-review/references/wave-3-adversarial.mdmarkdown6.8 KB
references/dag-compatibility-matrix.mdmarkdown13.0 KB
references/dag-composition-patterns.mdmarkdown5.0 KB
references/dag-orchestration-advanced.mdmarkdown6.3 KB
references/dag-orchestration-examples.mdmarkdown11.4 KB
references/dag-skill-patterns.mdmarkdown12.5 KB
references/de-ai-pipeline.jsscript14.3 KB
references/de-ai-pipeline.mdmarkdown6.3 KB
references/discover_skills.pyscript12.1 KB
references/do-perspectives.mdmarkdown11.4 KB
references/doc-pipeline.mdmarkdown9.2 KB
references/domain-research.mdmarkdown31.8 KB
references/domain-research/references/task-type-guide.mdmarkdown11.4 KB
references/explore-pipeline.jsscript18.2 KB
references/explore-pipeline.mdmarkdown15.0 KB
references/fan-out-workflow.jsscript9.8 KB
references/fan-out-workflow.pyscript9.6 KB
references/feedback-loop-construction.mdmarkdown14.3 KB
references/fl-design.mdmarkdown9.6 KB
references/fl-error-handling.mdmarkdown8.5 KB
references/fl-implement.mdmarkdown7.5 KB
references/fl-pipeline.mdmarkdown6.0 KB
references/fl-plan.mdmarkdown10.8 KB
references/fl-release.mdmarkdown3.8 KB
references/fl-shared.mdmarkdown3.6 KB
references/fl-validate.mdmarkdown4.5 KB
references/github-profile-rules.mdmarkdown10.3 KB
references/github-profile-rules/references/rule-categories.mdmarkdown6.5 KB
references/hc-SPEC.mdmarkdown3.3 KB
references/hc-domain-playbooks.mdmarkdown15.3 KB
references/hc-ledger.mdmarkdown3.3 KB
references/hc-profiling-tools.mdmarkdown3.7 KB
references/hill-climb.mdmarkdown9.3 KB
references/hook-development-pipeline.mdmarkdown12.9 KB
references/mcp-pipeline-builder.mdmarkdown16.4 KB
references/mcp-pipeline-builder/references/analysis-checklist.mdmarkdown6.2 KB
references/mcp-pipeline-builder/references/design-rules.mdmarkdown7.1 KB
references/mcp-pipeline-builder/references/evaluation-guide.mdmarkdown7.6 KB
references/mcp-pipeline-builder/references/python-scaffold-template.mdmarkdown9.5 KB
references/mcp-pipeline-builder/references/ts-scaffold-template.mdmarkdown1.6 KB
references/mcp-pipeline-builder/scripts/assemble-scaffold.pyscript6.3 KB
references/mcp-pipeline-builder/scripts/register_mcp.pyscript6.9 KB
references/mcp-pipeline-builder/templates/client-cli.ts.tmplother682 B
references/mcp-pipeline-builder/templates/client-http.ts.tmplother1.4 KB
references/mcp-pipeline-builder/templates/index.ts.tmplother1.1 KB
references/mcp-pipeline-builder/templates/package.json.tmplother477 B
references/mcp-pipeline-builder/templates/readme.md.tmplother1.1 KB
references/mcp-pipeline-builder/templates/tools.ts.tmplother3.0 KB
references/mcp-pipeline-builder/templates/ts-scaffold.tmplother556 B
references/mcp-pipeline-builder/templates/tsconfig.json.tmplother408 B
references/ol-SPEC.mdmarkdown2.4 KB
references/ol-state-file.mdmarkdown2.9 KB
references/pipeline-index.jsonconfig22.9 KB
references/pipeline-retro.mdmarkdown19.0 KB
references/pipeline-scaffolder.mdmarkdown19.3 KB
references/pipeline-scaffolder/references/architecture-rules.mdmarkdown17.3 KB
references/pipeline-scaffolder/references/generated-skill-template.mdmarkdown1.6 KB
references/pipeline-scaffolder/references/pipeline-spec-format.mdmarkdown34.8 KB
references/pipeline-scaffolder/references/step-menu.mdmarkdown21.5 KB
references/pipeline-scaffolder/scripts/assemble-skill.pyscript5.9 KB
references/pipeline-scaffolder/templates/phases/decision-planning.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/domain-extension.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/generation.md.tmplother427 B
references/pipeline-scaffolder/templates/phases/git-release.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/phases/interaction.md.tmplother965 B
references/pipeline-scaffolder/templates/phases/learning-retro.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/observation.md.tmplother1.3 KB
references/pipeline-scaffolder/templates/phases/research-gathering.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/review.md.tmplother930 B
references/pipeline-scaffolder/templates/phases/safety-guarding.md.tmplother1.7 KB
references/pipeline-scaffolder/templates/phases/structuring.md.tmplother361 B
references/pipeline-scaffolder/templates/phases/synthesis-reporting.md.tmplother1.9 KB
references/pipeline-scaffolder/templates/phases/validation.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/skill-template.md.tmplother12.0 KB
references/pipeline-test-runner.mdmarkdown16.5 KB
references/pl-ambiguity-triage.mdmarkdown2.7 KB
references/pl-check-dimensions.mdmarkdown7.4 KB
references/pl-check-errors.mdmarkdown824 B
references/pl-check-verdict-format.mdmarkdown3.2 KB
references/pl-check.mdmarkdown6.5 KB
references/pl-context-boundary.mdmarkdown1.6 KB
references/pl-depth-first-interview.mdmarkdown11.6 KB
references/pl-empirical-prototype.mdmarkdown825 B
references/pl-executor-ready-plan-template.mdmarkdown7.7 KB
references/pl-human-source-elicitation.mdmarkdown1.5 KB
references/pl-manage.mdmarkdown5.1 KB
references/pl-pause-confirm-and-errors.mdmarkdown2.1 KB
references/pl-pause-extract-decisions.mdmarkdown3.0 KB
references/pl-pause-gather-steps.mdmarkdown2.3 KB
references/pl-pause-synthesize-fields.mdmarkdown2.3 KB
references/pl-pause-write-templates.mdmarkdown5.3 KB
references/pl-pause.mdmarkdown6.5 KB
references/pl-plan-files.mdmarkdown8.4 KB
references/pl-pre-plan.mdmarkdown11.6 KB
references/pl-resume.mdmarkdown12.3 KB
references/pl-spec.mdmarkdown5.2 KB
references/pr-fix-loop.mdmarkdown10.3 KB
references/pr-fix-loop/references/message-formats.mdmarkdown1.6 KB
references/pr-fix-loop/references/publish.mdmarkdown5.4 KB
references/pr-fix-loop/references/review-checklist.mdmarkdown3.4 KB
references/pr-pipeline/references/pr-templates.mdmarkdown5.4 KB
references/pr-pipeline/references/preflight-checklist.mdmarkdown2.8 KB
references/pr-pipeline/references/retro-adr-phases.mdmarkdown2.7 KB
references/pr-pipeline/references/review-fix-loop.mdmarkdown2.0 KB
references/research-pipeline.jsscript14.6 KB
references/skill-creation-pipeline.mdmarkdown17.0 KB
references/system-upgrade.mdmarkdown12.4 KB
references/systematic-debugging.mdmarkdown11.0 KB
references/systematic-refactoring.mdmarkdown11.4 KB
references/toolkit-improvement.jsscript38.2 KB
references/toolkit-improvement.mdmarkdown20.3 KB
references/toolkit-improvement/references/adr-template.mdmarkdown10.4 KB
references/toolkit-improvement/references/agent-roster.mdmarkdown15.8 KB
references/workflow-helpers.jsscript10.1 KB
references/workflow-orchestrator.mdmarkdown20.8 KB
references/workflow-orchestrator/references/plan-template.mdmarkdown1.3 KB
references/workflow-orchestrator/references/task-patterns.mdmarkdown23.3 KB
references/workflow-orchestrator/scripts/assemble-plan.pyscript6.9 KB
references/workflow-orchestrator/scripts/validate.pyscript14.4 KB
references/workflow-orchestrator/templates/plan-template.json.tmplother904 B

references/systematic-debugging.md

View on GitHub
---
description: "Evidence-based 5-phase debugging: OBSERVE, HYPOTHESIZE, TEST, FIX, RECORD."
effort: high
user-invocable: false
context: fork
allowed-tools: [Read, Write, Bash, Grep, Glob, Edit, Task]
success-criteria:
  - "Bug is reproducible with a specific test or command"
  - "Root cause identified with evidence (not speculation)"
  - "Fix verified by running the reproduction step"
  - "No regressions in related test suite"
  - "Debug pattern recorded to the knowledge base"
routing:
  triggers:
    - "debug"
    - "find root cause"
    - "reproduce bug"
    - "fix this bug"
    - "this is broken"
    - "not working"
    - "why is this broken"
    - "getting an error"
    - "unexpected behavior"
    - "investigate error"
  category: process
---

# Systematic Debugging Pipeline

> **Promoted from**: `skills/systematic-debugging/SKILL.md` (original 4-phase skill)

Evidence-based 5-phase debugging pipeline with mandatory gates between each phase. No phase may be skipped. Each phase produces artifacts that survive context resets.

---

## Instructions

### Phase 1: OBSERVE

**Goal**: Reproduce the bug, collect error messages, stack traces, and environmental context.

**Artifact**: `debug-observations.md`

**Core Principle**: Reproduce first, always. Create a reliable reproduction before attempting any fix. This prevents you from chasing the wrong problem and ensures you can verify any fix actually works.

**Step 1: Document the bug**

```markdown
## Bug: [Brief Description]
Expected: [What should happen]
Actual: [What actually happens]
Environment: [OS, language version, dependencies]
```

**Step 2: Create minimal reproduction**

- Strip to essentials -- remove unrelated code
- Use smallest dataset that shows the bug
- Isolate from external services where possible

**Step 3: Verify consistency**

Run reproduction **3 times**. If inconsistent, identify variables (timing, randomness, concurrency) and add controls to make it deterministic. Consistency is not optional -- if you can't reproduce it reliably, you cannot verify a fix.

**Step 4: Check knowledge base**

At the start of every new debug investigation, before forming any hypotheses:

1. Check if `.debug-knowledge-base.md` exists in the project root
2. If it exists, search for keyword matches against the current symptom signature
3. Matches are **hypothesis candidates**, not confirmed diagnoses
4. List any matches in `debug-observations.md` with the note: "Prior resolution found -- verify applicability before assuming same root cause"

**Step 5: Create persistent debug file**

Create `.debug-session.md` with immutable Symptoms and Reproduction Steps sections. This file survives context resets.

| Section Type | Sections | Mutation Rule |
|-------------|----------|---------------|
| IMMUTABLE | Symptoms, Reproduction Steps | Write once at session start, never modify |
| APPEND-ONLY | Evidence, Eliminated Hypotheses | Add new entries, never remove or edit existing ones |
| OVERWRITE | Current Hypothesis, Next Action | Replace on each iteration |

**GATE**: Bug reproduces 100% with documented steps. `debug-observations.md` exists with symptoms, environment, and reproduction steps. Proceed only when gate passes.

---

### Phase 2: HYPOTHESIZE

**Goal**: Generate 3-5 candidate root causes ranked by likelihood.

**Artifact**: Updated `debug-observations.md` with hypotheses section.

**Core Principle**: Form evidence-based hypotheses, not random guesses. Each hypothesis must have concrete evidence supporting it, and each must be testable. One change at a time -- multiple simultaneous changes hide which one fixed it.

**Step 1: List components involved in the failure**

```markdown
## Components
1. [Component A] - [Role]
2. [Component B] - [Role]
3. [Component C] - [Role]
```

**Step 2: Binary search to narrow scope**

Test components in combinations to find minimal failing set:
- A alone -> PASS/FAIL?
- A + B -> PASS/FAIL?
- A + B + C -> PASS/FAIL?

When adding a component causes failure, that component (or its interaction) contains the bug.

**Step 3: Trace execution path**

Add targeted logging at decision points in the suspect component. Run and analyze:
- Where does execution diverge from expected?
- What values are unexpected at critical points?
- Are exceptions being caught silently?

**Step 4: Form ranked hypotheses**

```markdown
## Hypothesis: [Specific, testable statement]
Evidence: [What observations support this]
Test: [How to confirm or refute]
Likelihood: [HIGH/MEDIUM/LOW]
```

Generate 3-5 hypotheses. Rank by likelihood based on evidence gathered so far.

**Step 5: Update persistent debug file**

Write current top hypothesis and next action to `.debug-session.md` BEFORE taking any debugging action. This creates an audit trail that survives context resets.

**Pattern Trap**: Always validate with data before making changes. "I can see the bug" misses edge cases and is not evidence. Form a hypothesis, test it with data, then decide.

**GATE**: At least 3 hypotheses documented with supporting evidence and test plans. Identified smallest code path and input that reproduces the bug. Proceed only when gate passes.

---

### Phase 3: TEST

**Goal**: Write the minimal reproduction test, verify it fails (red).

**Artifact**: Reproduction test + test results

**Core Principle**: Verify the bug with a test before attempting any fix. The test is the oracle that tells you when the bug is truly fixed. If 5+ consecutive Read/Grep/Glob calls occur without an Edit/Write/Bash action, STOP and explain what you're looking for and why before proceeding. Document the justification in `.debug-session.md` under Current Hypothesis -- this creates an audit trail of investigation decisions.

**Step 1: Write reproduction test**

Create a test that captures the exact bug behavior:

```python
def test_regression_[issue]():
    """Root cause: [hypothesis]. Fix: [pending]."""
    result = buggy_function(trigger_input)
    assert result == expected  # This should FAIL
```

**Step 2: Test each hypothesis**

For each hypothesis (highest likelihood first):

```markdown
## Testing: [Hypothesis]
Experiment: [What I did]
Result: CONFIRMED / REFUTED
Evidence: [What I observed]
```

If REFUTED: Move to next hypothesis. Append to Eliminated Hypotheses in `.debug-session.md`.
If CONFIRMED: Proceed to Phase 4.

**Step 3: Code inspection checklist**

For the confirmed hypothesis area:
- [ ] Off-by-one errors?
- [ ] Null/None values unhandled?
- [ ] Exceptions caught silently?
- [ ] Race conditions possible?
- [ ] Resources released properly?
- [ ] Input assumptions violated?

**GATE**: Reproduction test exists and is RED (failing). Root cause hypothesis confirmed with evidence. Can explain WHY bug occurred. Proceed only when gate passes.

---

### Phase 4: FIX

**Goal**: Implement fix, verify test turns green. Ensure no regressions.

**Artifact**: Green test + passing full suite

**Core Principle**: Fix only the confirmed root cause. No speculative improvements, no "while I'm here" changes. Simple changes cause complex regressions -- complete all verification steps. If a specific test passes but the full suite fails, you have introduced regressions. Run the full suite every time.

**Step 1: Make the smallest possible fix**

Address only the confirmed root cause. No speculative improvements.

**Step 2: Verify reproduction test passes**

Run the reproduction test. It must turn GREEN. If it doesn't, the fix didn't work and you need to return to Phase 2 with new hypotheses.

**Step 2a: Revert on failed fix**

If the fix attempt fails (test stays RED) or creates more breakage than it solves (new failures outweigh the one fixed):

1. Revert all changes made since Phase 1 -- `git checkout -- <files>` or `git stash` the fix attempt. The codebase returns to its pre-fix state before any new hypothesis is tried.
2. Append the revert reason to `.debug-session.md` Eliminated Hypotheses -- record which hypothesis was tried, what broke, and why it was reverted.
3. Return to Phase 2 with narrowed scope -- the failed attempt is evidence; use it to rule out the hypothesis and rank the remaining candidates.

**Step 3: Test edge cases**

Test boundary values, empty input, null, maximum values. Verify the fix works beyond the exact reproduction case.

**Step 4: Run full test suite**

Verify no regressions. ALL tests must pass. Tests relied on buggy behavior, or fix changed API contract? If tests expected buggy behavior -> update tests. If fix exposed other bugs -> apply 5-phase process to each.

**Step 5: Test related functionality**

Check similar patterns that might share the same root cause. A root cause can appear in multiple places.

**Step 6: Document fix summary**

```markdown
## Fix Summary
Bug: [description]
Root Cause: [exact cause]
Fix: [changes made]
Files: [modified files]
Testing: reproduction passes, edge cases pass, full suite passes
```

**GATE**: Reproduction test is GREEN. Full test suite passes with zero regressions. Fix is minimal and addresses only the confirmed root cause. Proceed only when gate passes.

---

### Phase 5: RECORD

**Goal**: Record the pattern and fix in the repo's knowledge base for future sessions.

**Artifact**: Updated `.debug-knowledge-base.md`

**Step 1: Record to knowledge base**

Append entry to `.debug-knowledge-base.md`:

```markdown
## [Date] [Brief Description]
**Keywords**: [comma-separated terms: error messages, component names, symptom descriptions]
**Symptom**: [What was observed]
**Root Cause**: [What was actually wrong]
**Resolution**: [What fixed it]
**Files**: [Which files were involved]
```

**Step 2: Clean up**

- Remove `.debug-session.md` (investigation complete)
- Remove temporary debug logs and profiling output
- Keep only the regression test and knowledge base entry

**Output**: `Bug pattern recorded in .debug-knowledge-base.md.`

**GATE**: Knowledge base entry exists with keywords, symptom, root cause, and resolution. `.debug-session.md` cleaned up. Temporary files removed.

---

## Error Handling

### Error: "Cannot Reproduce Bug"
Cause: Environmental differences, timing-dependent, or randomness
Solution:
1. Match environment exactly (OS, versions, dependencies)
2. Look for race conditions or async timing issues
3. Introduce determinism (fixed seeds, mocked time)
4. If intermittent: add monitoring to catch it in-flight

### Error: "Fix Breaks Other Tests"
Cause: Tests relied on buggy behavior, or fix changed API contract
Solution:
1. If tests expected buggy behavior -> update tests
2. If fix exposed other bugs -> apply 5-phase process to each
3. If API changed -> restore compatibility or update all callers

### Error: "Root Cause Still Unclear After Isolation"
Cause: Isolation not narrow enough, or multiple contributing factors
Solution:
1. Return to Phase 2 with narrower scope
2. Add logging at lower abstraction levels
3. Use debugger to step through execution
4. Consult `references/debugging-patterns.md` for common patterns

---

## References

### Reference Files
- `${CLAUDE_SKILL_DIR}/references/debugging-patterns.md`: Common bug patterns by category
- `${CLAUDE_SKILL_DIR}/references/tools.md`: Language-specific debugging tools
- `${CLAUDE_SKILL_DIR}/references/isolation-techniques.md`: Advanced isolation strategies
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall