@martinffx/atelier 0.1.0

package/skills/code-debug/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: code-debug
+description: >
+  Systematic debugging workflow and techniques. Use when something is broken, not working as
+  expected, or throwing errors. Covers reproduction, isolation, hypothesis formation, fix
+  implementation, and verification. Also triggers on "why does X fail", "debug this", "this
+  is broken", or when encountering errors or unexpected behavior.
+user-invocable: true
+---
+
+# Code Debug
+
+Systematic debugging workflow to find and fix bugs efficiently. Never guess — always
+narrow down the problem through systematic elimination.
+
+## The Debugging Mindset
+
+| Bad | Good |
+|-----|------|
+| "I think it's..." | "Let me verify..." |
+| Changing random things | Binary search narrowing |
+| Hoping it'll work | Verifying each hypothesis |
+| Moving on after it works | Adding regression test |
+
+## The Five-Step Workflow
+
+### Step 1: Reproduce
+
+Create the smallest possible reproduction case.
+
+**Questions to answer:**
+- What exactly triggers the bug?
+- Can I make it happen on demand?
+- What's the minimal input that causes it?
+
+**Techniques:**
+- Extract exact steps from bug report
+- Remove unrelated factors
+- Create a minimal test case
+
+**Output:** "I can reproduce the bug by [exact steps]."
+
+---
+
+### Step 2: Isolate
+
+Narrow down where the bug lives using binary search.
+
+**Binary search strategies:**
+- Comment out half the code → does it still fail?
+- Isolate by layer: is it the UI, service, or data layer?
+- Isolate by file: which file contains the bug?
+- Isolate by function: which function causes the issue?
+
+**Git bisect** (for regression bugs):
+```bash
+git bisect start
+git bisect bad  # current commit is broken
+git bisect good <last-working-commit>
+# Run tests, mark good/bad
+git bisect reset  # done
+```
+
+**Output:** "The bug is in [specific file/function/component]."
+
+---
+
+### Step 3: Form Hypothesis
+
+Make a testable guess about the root cause.
+
+**Good hypothesis:**
+- Specific: "The user ID is undefined because..."
+- Testable: Can verify with a test or log
+- Grounded: Based on evidence, not guess
+
+**Questions to ask:**
+- Why does this happen?
+- What are the preconditions?
+- What's the actual vs expected behavior?
+- What changed recently?
+
+**Output:** "I hypothesize that [root cause] because [evidence]."
+
+---
+
+### Step 4: Fix
+
+Implement the fix based on your hypothesis.
+
+**Rules:**
+- Make minimal changes
+- Don't refactor while fixing (separate concerns)
+- Write failing test first if possible
+- Consider edge cases
+
+**Fix patterns:**
+- **Missing value** → Add null check or default
+- **Wrong value** → Correct the logic
+- **Exception** → Handle the error case
+- **Logic error** → Fix the condition
+
+**Output:** "Fix applied: [brief description]."
+
+---
+
+### Step 5: Verify
+
+Confirm the fix works and doesn't break anything.
+
+**Verification steps:**
+1. Run the reproduction case → should pass now
+2. Run related tests → should pass
+3. Run full test suite → should pass
+4. Add regression test → prevents future breakage
+
+**Output:** "Fix verified. Tests passing. Regression test added."
+
+---
+
+## Debugging Techniques
+
+### Print Debugging
+
+Quick and dirty, but sometimes the fastest way.
+
+**When to use:**
+- Quick checks in development
+- When debugger isn't available
+- Understanding flow in unfamiliar code
+
+**Best practices:**
+- Print at entry/exit of functions
+- Print variable values at key points
+- Remove print statements before committing
+- Consider structured logging instead
+
+### Debugger
+
+More powerful than print debugging.
+
+**When to use:**
+- Complex state to inspect
+- Stepping through logic
+- Evaluating expressions in context
+
+**See references/language-tools.md for language-specific debugger commands.**
+
+### Logging
+
+Better than print for production issues.
+
+**Strategies:**
+- Add context: request ID, user ID, correlation IDs
+- Log at appropriate levels: DEBUG, INFO, WARN, ERROR
+- Don't log sensitive data
+- Structured logging (JSON) for easier parsing
+
+**See references/techniques.md for logging patterns.**
+
+### Binary Search
+
+Halving the search space.
+
+**Strategies:**
+- Comment out code blocks
+- Test with half the data
+- Compare working vs broken configurations
+- Git bisect for regressions
+
+### Rubber Ducking
+
+Explain the problem out loud (or to a rubber duck).
+
+**Process:**
+1. Describe the problem in detail
+2. Explain what you expect to happen
+3. Explain what's actually happening
+4. Often the solution becomes clear mid-explanation
+
+---
+
+## Common Bug Patterns
+
+### Null/Undefined Errors
+
+**Symptoms:** Cannot read property X of undefined
+
+**Debug approach:**
+1. Find where the value becomes undefined
+2. Trace back where it should come from
+3. Add guard or fix source
+
+**Fix patterns:**
+```javascript
+// Before
+const name = user.profile.name;
+
+// After
+const name = user?.profile?.name ?? 'Unknown';
+// or
+if (!user?.profile) return;
+const name = user.profile.name;
+```
+
+### Race Conditions
+
+**Symptoms:** Intermittent failures, flaky tests
+
+**Debug approach:**
+1. Identify async operations
+2. Find timing dependencies
+3. Add delays or force ordering
+
+**Fix patterns:**
+- Use async/await properly
+- Add proper synchronization
+- Consider immutable state
+
+### Logic Errors
+
+**Symptoms:** Wrong output, wrong behavior
+
+**Debug approach:**
+1. Trace through the logic manually
+2. Compare expected vs actual at each step
+3. Find the first step that diverges
+
+**Fix patterns:**
+- Fix the condition
+- Correct the calculation
+- Update the state correctly
+
+### Performance Issues
+
+**Symptoms:** Slow, memory leaks, timeouts
+
+**Debug approach:**
+1. Measure first (don't guess)
+2. Identify hot paths
+3. Optimize the bottleneck
+
+**See code-perf skill for detailed performance debugging.**
+
+---
+
+## Skill Loading
+
+Check available skills for additional debugging support:
+
+- If dealing with performance issues → load code-perf
+- If security vulnerability suspected → load code-security
+- If debugging tests → load oracle-testing
+
+---
+
+## Output Format
+
+After each debugging session, summarize:
+
+```
+## Debug Summary
+
+**Problem:** [One sentence]
+**Root Cause:** [What actually was wrong]
+**Fix:** [How you fixed it]
+**Verification:** [Test results]
+**Prevention:** [Regression test added?]
+```
+
+This helps future-you understand what happened.

package/skills/code-debug/references/language-tools.md

@@ -0,0 +1,139 @@
+# Debugging Tools by Language
+
+## Node.js
+
+### Node Inspector / Chrome DevTools
+
+```bash
+# Start with debugging
+node --inspect server.js
+
+# Break on first line
+node --inspect-brk server.js
+```
+
+Then open chrome://inspect in Chrome.
+
+### VS Code Debugging
+
+Create .vscode/launch.json:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Debug Server",
+  "program": "${workspaceFolder}/server.js",
+  "console": "integratedTerminal"
+}
+```
+
+### ndb
+
+Better debugging for Node:
+
+```bash
+npm install -g ndb
+ndb server.js
+```
+
+### console.table
+
+```javascript
+const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}];
+console.table(users);
+```
+
+---
+
+## Python
+
+### pdb
+
+```python
+import pdb
+
+def calculate():
+    x = 10
+    pdb.set_trace()  # Break here
+    y = x * 2
+    return y
+
+# Commands: n (next), s (step), p x (print), l (list), w (where), c (continue)
+```
+
+### ipdb (better pdb)
+
+```bash
+pip install ipdb
+import ipdb; ipdb.set_trace()
+```
+
+### VS Code
+
+Just set breakpoint and press F5.
+
+### PyCharm
+
+Right-click → Debug.
+
+---
+
+## Go
+
+### Delve
+
+```bash
+# Install
+go install github.com/go-delve/delve/cmd/dlv@latest
+
+# Run
+dlv debug main.go
+
+# Commands: n (next), s (step), p x (print), bt (backtrace), c (continue)
+```
+
+### VS Code
+
+Just set breakpoint and press F5.
+
+---
+
+## Rust
+
+### LLDB with VS Code
+
+```json
+{
+  "type": "lldb",
+  "request": "launch",
+  "program": "${workspaceFolder}/target/debug/myapp",
+  "args": ["--arg1", "value"]
+}
+```
+
+### Rust Analyzer
+
+Hover over variable → "Debug" button.
+
+---
+
+## Browser (JavaScript)
+
+### Chrome DevTools
+
+1. F12 → Sources tab
+2. Find file
+3. Set breakpoint
+4. Refresh page
+
+### Firefox DevTools
+
+1. F12 → Debugger tab
+2. Find file
+3. Set breakpoint
+4. Refresh page
+
+### VS Code
+
+Use "Debug JavaScript" or "Debug Edge" configuration.

package/skills/code-debug/references/techniques.md

@@ -0,0 +1,117 @@
+# Debugging Techniques
+
+## Print Debugging
+
+### When to Use
+- Quick checks in development
+- When debugger isn't available
+- Understanding flow in unfamiliar code
+- Minimal reproducible cases
+
+### Best Practices
+
+**Do:**
+- Print at function entry/exit to trace execution
+- Print variable values at key decision points
+- Use descriptive labels: console.log('userId:', userId)
+- Print full objects for inspection: console.log(JSON.stringify(data, null, 2))
+
+**Don't:**
+- Leave print statements in production code
+- Print sensitive data (passwords, tokens)
+- Over-print (noise obscures signal)
+- Print in tight loops (use breakpoints instead)
+
+### Structured Logging
+
+Better than console.log for production:
+
+```javascript
+const logger = {
+  debug: (msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, ...meta })),
+  info: (msg, meta) => console.info(JSON.stringify({ level: 'info', msg, ...meta })),
+  warn: (msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, ...meta })),
+  error: (msg, meta) => console.error(JSON.stringify({ level: 'error', msg, ...meta })),
+};
+```
+
+### Console Methods
+
+| Method | Use |
+|--------|-----|
+| console.log | General output |
+| console.debug | Debug info |
+| console.info | Informational |
+| console.warn | Warnings |
+| console.error | Errors |
+| console.table | Arrays/objects in table format |
+| console.trace | Stack trace |
+| console.time/timeEnd | Timing |
+
+---
+
+## Binary Search Debugging
+
+### Code Binary Search
+
+Comment out half the code to find where the bug is.
+
+### Git Bisect
+
+For regression bugs:
+
+```bash
+git bisect start
+git bisect bad
+git bisect good v1.2.3
+# Run your test, mark good/bad
+git bisect reset
+```
+
+---
+
+## Rubber Ducking
+
+### The Process
+
+1. Describe the problem in detail
+2. Explain expected behavior
+3. Explain actual behavior
+4. Walk through the code line by line
+
+---
+
+## Logging Strategies
+
+### What to Log
+
+| Log This | Don't Log This |
+|----------|----------------|
+| Request/response with IDs | Full request bodies |
+| Key decisions in code | Every loop iteration |
+| Error details with context | Stack traces |
+| Performance timing | Large data dumps |
+| User actions | Sensitive data (PII, passwords) |
+
+### Context to Include
+
+```javascript
+logger.error('Request failed', {
+  endpoint: '/api/users',
+  method: 'POST',
+  statusCode: 500,
+  userId: user?.id,
+  requestId: req.headers['x-request-id'],
+  duration: Date.now() - startTime,
+  errorMessage: error.message
+});
+```
+
+### Log Levels
+
+| Level | When |
+|-------|------|
+| DEBUG | Detailed debugging info |
+| INFO | Normal operation events |
+| WARN | Something unexpected, but handled |
+| ERROR | Operation failed |

package/skills/code-docs/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: code-docs
+description: >
+  Documentation generation for code projects. Use when updating docs, writing README, generating
+  API docs, creating changelog, or when the user mentions documentation, docs, readme, api docs,
+  or any documentation task.
+user-invocable: true
+---
+
+# Code Docs
+
+Documentation generation and maintenance for code projects.
+
+## When to Document
+
+**Always update docs when:**
+- Adding new features
+- Changing existing behavior
+- Updating configuration
+- Breaking changes
+
+**Docs should live:**
+- Near the code (docstrings, comments)
+- In the repo (README, docs folder)
+- Generated (API docs, type docs)
+
+---
+
+## Doc Types
+
+### README
+
+Project overview, setup, usage. See references/readme-structure.md
+
+**Template:**
+```markdown
+# Project Name
+
+Brief description (one line).
+
+## Quick Start
+
+3-5 commands to get running.
+
+## Installation
+
+Detailed setup steps.
+
+## Usage
+
+Code examples.
+
+## API
+
+Link to full API docs.
+
+## Contributing
+
+How to contribute.
+
+## License
+```
+
+### API Documentation
+
+See references/api-docs.md for:
+- TypeDoc (JavaScript/TypeScript)
+- Sphinx (Python)
+- godoc (Go)
+- JSDoc (JavaScript)
+
+### Changelog
+
+See references/changelog.md for Keep a Changelog format.
+
+**Sections:**
+- Added
+- Changed
+- Deprecated
+- Removed
+- Fixed
+- Security
+
+### Architecture Docs
+
+See references/architecture-docs.md for:
+- ADRs (Architecture Decision Records)
+- Diagrams
+- System overviews
+
+---
+
+## Generation Commands
+
+### TypeScript/JavaScript
+
+```bash
+# TypeDoc
+npx typedoc --out docs src/index.ts
+
+# JSDoc
+npx jsdoc src/ -d docs/
+
+# API Extractor (monorepos)
+npx api-extractor run
+```
+
+### Python
+
+```bash
+# Sphinx
+sphinx-build -b html docs docs/_build
+
+# pdoc
+pdoc --output-dir docs src/
+
+# mkdocs
+mkdocs serve
+```
+
+### Go
+
+```bash
+# godoc
+godoc -http=:6060
+
+# swag (OpenAPI from comments)
+swag init -g cmd/server/main.go
+```
+
+---
+
+## Workflow
+
+### 1. Identify what needs docs
+
+- New files/features → update relevant doc
+- Breaking change → update CHANGELOG
+- New public API → update API docs
+
+### 2. Generate/Update
+
+- Run doc generators
+- Update manual docs
+- Verify examples work
+
+### 3. Verify
+
+- Links work
+- Examples run
+- Build passes
+
+### 4. Commit
+
+```
+docs: update API documentation
+
+Generated via typedoc.
+Added: new /users endpoint
+Changed: authentication section
+```
+
+---
+
+## Best Practices
+
+1. **Write docs in the code** - Docstrings, comments
+2. **Generate where possible** - Don't duplicate
+3. **Keep README minimal** - Link to detailed docs
+4. **Version with code** - Docs in same repo/PR
+5. **Test examples** - Ensure they run