@blulotus/trellis 0.7.0

package/dist/templates/common/skills/break-loop.md

@@ -0,0 +1,184 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | Strict type checking, no escape hatches | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/spec/guides/` thinking guides
+- [ ] Update relevant `.trellis/spec/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check guidelines if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.
+
+
+## Thinking Framework: Bayesian Reasoning
+
+When multiple root causes are plausible and evidence is incomplete, update your beliefs proportionally to new evidence rather than clinging to initial assumptions.
+
+### Step 1: Establish Priors
+
+Before investigating, state what you believe and why:
+
+| Hypothesis | Prior | Reasoning |
+|------------|-------|-----------|
+| H1: [cause A] | 40% | Most common for this pattern |
+| H2: [cause B] | 30% | Plausible given environment |
+| H3: [other] | 30% | Catch-all |
+
+Priors must sum to 100%. If you can't assign probabilities, investigate first.
+
+### Step 2: Observe Evidence
+
+Document what you found — be specific about reliability:
+
+- What exactly did you observe?
+- How reliable? (test output > log message > user report > hunch)
+- Could multiple hypotheses explain this?
+
+### Step 3: Update Beliefs
+
+For each hypothesis, ask: **How likely is this evidence if this hypothesis were true?**
+
+Direction of update matters more than calculation:
+- Evidence strongly predicted by H1 → H1 probability increases
+- Evidence contradicts H2 → H2 probability decreases
+- Evidence equally likely under all → no update
+
+### Step 4: Seek Discriminating Evidence
+
+Don't gather more of the same. Find evidence that **differs strongly** between top hypotheses.
+
+> If H1 and H3 are close: "What would I see if H1 is true but not if H3 is true?" Then check for that.
+
+### Step 5: State Confidence
+
+| Confidence | Action |
+|------------|--------|
+| 90%+ | Proceed with fix, monitor |
+| 70-90% | Proceed, add fallback check |
+| 50-70% | Test hypothesis before committing |
+| <50% | Need more evidence, don't guess |
+
+Never express binary certainty when evidence is incomplete. Use "most likely", "plausible but unlikely", "worth investigating".
+
+### Common Fallacies
+
+| Fallacy | Example | Correction |
+|---------|---------|------------|
+| **Base rate neglect** | "Test failed → code is broken" | How often do tests fail for other reasons? |
+| **Confirmation bias** | "Must be a race condition, let me find race evidence" | Actively seek evidence AGAINST your top hypothesis |
+| **Anchoring** | "Last time it was caching, probably caching again" | Establish priors from current context, not yesterday's bug |
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**

package/dist/templates/common/skills/check.md

@@ -0,0 +1,106 @@
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Task Artifacts and Applicable Specs
+
+Read the current task artifacts in order:
+
+- `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+### Test Coverage
+
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
+
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+### Scope Discipline
+
+- [ ] Any tidying of code the task did not require?
+- [ ] Any abstraction, config or extension point added for a case that does not exist yet?
+- [ ] Any speculative fallback for a state that cannot occur?
+- [ ] Any file changed that the acceptance criteria do not mention?
+- [ ] Any workaround added at the caller instead of a fix where the behavior actually lives?
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If the same value repeats, does it represent one stable concept whose callers must change together? Extract only then — two literals that merely happen to match today should stay separate.
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report every violation you find. Then:
+
+- Mechanical and local (lint nit, missing type, wrong import, dead branch, failing assertion) → fix in place, then re-run project checks.
+- Design or judgment (naming a shared concept, moving a module boundary, changing a public interface, reassigning where behavior lives) → record the evidence and your recommendation, and stop. Do not rewrite it silently.
+
+If a fix would touch files outside the current task's scope, say so and stop instead of widening the change.

package/dist/templates/common/skills/tdd.md

@@ -0,0 +1,142 @@
+# Red Before Green
+
+No production code before red evidence.
+
+Red evidence is one command you have **already executed** that goes red on the exact thing you are about to change. For a bug that is the reproduction; for a feature it is a failing test at a confirmed seam. Both are the same primitive, and both exist so that "it works now" is a claim you can check instead of a claim you make.
+
+A lint pass, a successful build, or a green type-check is not red evidence. None of them can observe the behavior in question.
+
+---
+
+## Which Path Applies
+
+Read `meta.kind` from the active task's `task.json`.
+
+| `meta.kind` | Path | Gate |
+|---|---|---|
+| `bug` | Reproduce first — see **Bug Path** | Repro recorded in `research/repro-<topic>.md` before `task.py start` |
+| `feature` | Confirm seams, then slice — see **Feature Path** | Seam list in `design.md` before `task.py start`; red before green per slice |
+| `chore` | Exempt | — |
+
+If `meta.kind` is missing, ask the user and set it with `task.py set-meta <task-dir> kind <kind>`. Never guess it. `chore` covers config, docs, scaffolding, and mechanical moves — do not label a behavior change `chore` to escape the gate.
+
+---
+
+## Redact First
+
+This work captures commands and their output into task artifacts. Before pasting anything:
+
+- Replace secrets, tokens, credentials, private hostnames, and user data with `<REDACTED>`.
+- Read credentials from environment variables so they never appear in shown output.
+- Quote only the signal-bearing lines of a captured artifact.
+- If redaction removes so much that the evidence stops being useful, say so and ask the user how to proceed.
+
+---
+
+## Bug Path
+
+### 1. Build the loop
+
+A tight pass/fail signal that goes red on *this* bug is what makes everything downstream work. Invest disproportionate effort here — a theory assembled from reading code, with no command that goes red, is not a diagnosis.
+
+Approaches, roughly cheapest-first:
+
+- a failing test at any seam that reaches the bug
+- an HTTP script against a dev server
+- a CLI run against a fixture, diffed against known-good output
+- a headless browser script asserting on DOM, console, or network
+- replay of a saved trace or payload
+- a throwaway harness with the irrelevant dependencies stubbed
+- a property or fuzz loop over many generated inputs
+- a bisection harness suitable for `git bisect run`
+- differential runs of two versions or two configs
+
+Then tighten it: faster (cache setup, narrow scope), sharper (assert the specific symptom, not "something threw"), more deterministic (pin time, seed RNG, isolate filesystem and network). A flaky thirty-second loop is barely better than no loop.
+
+For intermittent bugs, aim at a workable reproduction *rate* rather than perfect determinism — loop it, parallelise it, add stress or injected delays. Around half the runs failing is workable; one percent is not.
+
+**Exit criterion**: name one command you have already run at least once, showing its redacted invocation and red output, that drives the real code path, asserts the user's exact symptom, is deterministic (or reliably flaky), is fast, and can be re-run without a human. Without that command, do not move on.
+
+**If you cannot build one**: stop and say so. List what you tried, and ask for what would unblock it — environment access, a redacted log/HAR/trace/core dump, or approval to instrument temporarily. Writing that down is a legitimate outcome. Quietly proceeding to a fix is not.
+
+### 2. Reproduce and minimise
+
+Run the loop and watch it fail. Verify the failure is the one that was reported, not a neighbouring one — the wrong bug gets the wrong fix.
+
+Then shrink to the smallest still-red scenario. Remove inputs, callers, config, data, and steps one at a time, re-running after each. Done when every remaining element is load-bearing. The minimal case narrows the hypothesis space and becomes the regression test.
+
+### 3. Hypothesise before probing
+
+List three to five ranked hypotheses *before* testing any of them. Each needs a prediction: *if X is the cause, then changing Y makes the bug disappear* (or *changing Z makes it worse*). A hypothesis with no prediction is a hunch — sharpen it or drop it.
+
+### 4. Instrument
+
+One probe per hypothesis, varying one thing at a time. Prefer a debugger or REPL over scattered logging; one breakpoint beats ten log lines. When you do log, log at the boundaries that distinguish hypotheses — never "log everything and grep".
+
+Tag every debug line with a unique prefix such as `[DEBUG-a4f2]` so removal is one grep. Untagged debug output survives into production.
+
+For performance regressions, logs are usually the wrong tool: take a baseline with a timing harness, profiler, or query plan, then bisect. Measure first, fix second.
+
+### 5. Fix with a regression test
+
+Convert the minimised reproduction into a failing test — but only at a seam that exercises the real bug pattern as it occurs at the call site. A single-caller unit test for a multi-caller bug gives false confidence. If no correct seam exists, that is itself the finding: record it as an architectural obstacle rather than testing at the wrong level.
+
+Then: watch the test fail, apply the fix, watch it pass, and re-run the step-1 loop against the original full scenario. A narrow test passing while the original repro is still red means the fix is incomplete.
+
+### 6. Clean up before claiming done
+
+- the original reproduction no longer reproduces, verified by re-running the step-1 loop
+- the regression test passes, or the missing seam is documented
+- every `[DEBUG-...]` line is gone
+- throwaway harnesses are deleted or moved to a clearly marked debug area
+- the confirmed cause is recorded in the commit message
+
+---
+
+## Feature Path
+
+### 1. Confirm the seams first
+
+No test is written at an unconfirmed seam. The seam is the public boundary the test sits on, and choosing it is a design decision that belongs to the user — ask *what is the public interface, and which seams should we test?* during planning, and record the answer in `design.md`.
+
+Implementation may not invent a seam. If the right seam is missing from `design.md`, that is a planning defect: go back to requirement exploration rather than improvising one.
+
+### 2. One slice per cycle
+
+A slice is one seam, one test, one minimal implementation. Per slice:
+
+1. Write the test at the confirmed seam.
+2. Run it. Watch it fail for the reason you expect — a test that fails because of a typo or a missing import is not red evidence.
+3. Paste the redacted red output into that slice's entry in `implement.md`.
+4. Write the minimum production code to make it pass. Run it again.
+5. Move to the next slice.
+
+Each cycle is a probe: let what it reveals reshape the remaining slices instead of committing to all of them up front.
+
+---
+
+## Prohibitions
+
+Both paths:
+
+- **No horizontal slicing** — writing every test first, then every implementation. That verifies imagined behavior and freezes the test structure before you have learned anything.
+- **No testing internals.** Tests sit on public boundaries. Reaching into private methods, mocking internal collaborators, or asserting through a side channel such as reading the database instead of the interface all couple the test to the implementation. Diagnostic: the test breaks under a pure refactor while behavior is unchanged.
+- **No tautological assertions.** An expected value must trace to an independent source — a known-good literal, a worked example, or the spec. Recomputing the expectation the same way the code does asserts nothing.
+- **No refactoring inside a red-green cycle.** Finish the cycle, then refactor as its own step.
+- **No speculative tests** for behavior nobody asked for yet.
+- **No silent skips.** A repo with no runnable harness, or a slice you decided not to test, must say so in the slice entry with the reason. Absence of a test is a fact to record, not a gap to leave blank.
+
+---
+
+## Recording the Evidence
+
+Nothing here lives only in the chat.
+
+| Evidence | Goes in |
+|---|---|
+| Bug reproduction: command, red output, minimised scenario | `research/repro-<topic>.md` |
+| Confirmed test seams | `design.md` |
+| Per-slice red output and completion | the slice entry in `implement.md` |
+| "No red-capable command", with what was tried and what is needed | `research/repro-<topic>.md`, or the slice entry |
+
+The quality check reads this trail. A slice claiming green with no recorded red is a finding, not a pass.