@brunosps00/dev-workflow 1.0.1 → 1.0.4

package/scaffold/skills/dw-codebase-intel/references/query-patterns.md

@@ -16,6 +16,8 @@ The command classifies the query into one of these shapes before searching:
 | **api-list** | "list endpoints", "what routes exist?" | `apis.json` | — |
 | **find-export** | "where is `createServer` exported from?", "find the `userSchema` symbol" | `files.json` (search `exports` arrays) | grep fallback |
 | **convention** | "what's the file naming convention?", "are tests co-located?" | `arch.md` | `.dw/rules/` if available |
+| **bugfix-history** | "bugs in `src/auth/`?", "recent fixes touching login?", "what broke in payments?", "fix history for the export feature" | `bugfixes.json` | `.dw/rules/concerns.md`, `.dw/bugfixes/<NNN-slug>/SUMMARY.md` for top hits |
+| **risk-area** | "is `src/auth/session.ts` risky?", "what's fragile here?", "where are the hot spots?", "tech debt in payments?" | `.dw/rules/concerns.md` | `bugfixes.json` (cross-ref bug history for the same module) |
 
 ## Match algorithm
 
@@ -122,6 +124,56 @@ Users (5)
 Orders (5) ...
 ```
 
+### Query: "bugs in src/auth/?"
+
+**Shape:** bugfix-history
+
+**Process:**
+1. Read `bugfixes.json`, look up `by_module["src/auth/"]`.
+2. For each slug returned, fetch the matching `fixes[]` entry (one-line symptom + root cause + date).
+3. Cross-reference `.dw/rules/concerns.md` — if `src/auth/` appears under Hot Spots or Known Bug History, surface that callout.
+4. Return chronological list with paths to the full SUMMARY.md for the top 3.
+
+**Output:**
+```
+3 historical fixes touched src/auth/ (concerns.md flags it as a Hot Spot — 4 fixes in 60d):
+
+- 007-refresh-token-leak   (2026-03-12, Fixed, High)
+  Symptom: refresh token survived sign-out
+  Root cause: session map keyed by user id, not session id
+  → .dw/bugfixes/007-refresh-token-leak/SUMMARY.md
+
+- 003-mfa-skip-on-redirect (2026-02-04, Fixed, Medium)
+  Symptom: redirect chain bypassed MFA check
+  → .dw/bugfixes/003-mfa-skip-on-redirect/SUMMARY.md
+
+- 001-login-not-working    (2026-01-20, Fixed, Medium)
+  Symptom: 500 on POST /login when email casing varied
+  → .dw/bugfixes/001-login-not-working/SUMMARY.md
+
+Consider adding a regression-test guard before further changes here.
+```
+
+### Query: "what's fragile in payments?"
+
+**Shape:** risk-area
+
+**Process:**
+1. Read `.dw/rules/concerns.md`. Search each section (Hot Spots, Fragile Integrations, Hostile Code, Known Bug History, Tech Debt) for `payments`.
+2. For Known Bug History matches, cross-reference `bugfixes.json` `by_module["src/payments/"]` to enumerate recent slugs.
+3. Return one paragraph per concerns.md section that matched, with cross-ref to the bugfix slugs.
+
+**Output:**
+```
+Three risk signals for src/payments/:
+
+Hot Spot: 5 commits in last 30 days; 2 historical bugfixes (refund-rounding, stripe-webhook-retry).
+Fragile Integration: Stripe webhook delivery — concerns.md notes "silent 200 OK when signature header is absent".
+Hostile Code: src/payments/parseInvoice.ts:parseLine — 900-char regex, no comments; original author flagged "rewrite if it breaks".
+
+See: .dw/rules/concerns.md, .dw/bugfixes/{002-stripe-webhook-retry,007-refund-rounding}/SUMMARY.md
+```
+
 ## Stale-index handling
 
 Before answering, check `.dw/intel/.last-refresh.json`:

package/scaffold/skills/dw-memory/SKILL.md

@@ -145,6 +145,29 @@ When flagged for compaction, apply inline:
 4. **Rewrite** retained items as short factual bullets. No narrative logs, no chronological play-by-play.
 5. Keep the default section headings intact. Remove empty sections only if truly unused.
 
+## Context Budget
+
+Memory is part of a broader **context budget** the agent must respect during execution. A blown budget degrades reasoning before any output is produced — the model starts missing requirements, drops constraints, and reverts to averaged-over-training answers. Full guidance: [`references/context-budget.md`](references/context-budget.md).
+
+**Targets:**
+
+- **Total active context:** under **40k tokens** (rough working budget across PRD + TechSpec + tasks + MEMORY.md + per-task memory + open files).
+- **Reserve:** at least **120k tokens** of headroom for actual reasoning, tool output, and the model's response stream.
+- **Hard ceiling per memory file:** `MEMORY.md` ≤ 6KB; `<N>_memory.md` ≤ 3KB. Past those, compact instead of growing.
+
+**Anti-co-load rules** (apply on every load):
+
+1. Never load two PRD specs in the same context. If switching PRDs, drop the previous PRD's spec/techspec/tasks references from the active set.
+2. Never load multiple archived `.dw/bugfixes/` SUMMARY.md files together — load only what's needed for the active fix or query.
+3. Never load `.dw/intel/files.json` and `.dw/intel/deps.json` simultaneously when answering a single question — pick the primary per query shape (see `dw-codebase-intel/references/query-patterns.md`).
+4. Never load a design proposal AND the prior design's full text — if comparing, summarize the prior into 5-10 lines.
+
+**Monitoring signal:**
+
+If the agent finds itself reading large files repeatedly or summarizing the same fact across multiple turns, that's a budget signal. Compact memory and explicitly drop unrelated loaded context before proceeding. Note this in `MEMORY.md` under Handoff Notes so the next task starts lean.
+
+This budget is doctrine, not a hard gate. No command currently rejects work for exceeding 40k. The discipline lives here because future sessions read this skill first.
+
 ## Error Handling
 
 - If any caller-provided memory path is missing, stop and report the mismatch instead of guessing another path.
@@ -165,6 +188,8 @@ Ported from Compozy's `cy-workflow-memory` skill (`/tmp/compozy/.agents/skills/c
 
 - Paths are `.dw/spec/<prd-slug>/` instead of `.compozy/tasks/<name>/`.
 - Task-local file is `<N>_memory.md` next to `<N>_task.md` (mirrors the existing dev-workflow task layout).
-- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); if the rule set grows, extract a `references/` directory later.
+- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); the budget discipline was extracted to `references/context-budget.md` because it's about model behavior, not file management.
 
 Credit: Compozy project (https://github.com/compozy/compozy).
+
+The Context Budget section adapts the context-loading discipline from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The target, the anti-co-load rules, and the "monitoring signal" framing come from there; the integration with two-tier memory and the specific file ceilings are dev-workflow-specific.

package/scaffold/skills/dw-memory/references/context-budget.md

@@ -0,0 +1,63 @@
+# Context Budget — Discipline
+
+A working context window is finite. Past about 40k tokens of active content, model output quality degrades — the model starts to miss requirements, lose constraints, blur details across sources, and revert to training-set averages. This file codifies the discipline that keeps active context lean across a long dev-workflow session.
+
+## The numbers
+
+- **Target active load:** under **40k tokens** total — PRD, TechSpec, tasks, MEMORY.md, per-task memory, all open files together.
+- **Reasoning reserve:** **120k+ tokens** of headroom for tool output, model thinking, and response generation.
+- **Soft alert:** when active load crosses **30k tokens**, plan to compact before the next major task.
+- **Compaction threshold for `MEMORY.md`:** ≤ 6KB on disk.
+- **Compaction threshold for `<N>_memory.md`:** ≤ 3KB on disk.
+
+These are doctrine, not enforced by any hard gate. The cost of breaking them is degraded output, not a command failure. Catch it yourself; the framework can't.
+
+## The anti-co-load rules
+
+Each is a "do not load both simultaneously" pairing. Pick one; if you must consult the other, summarize it to 5–10 lines first and drop the full version.
+
+1. **Two PRDs at once.** Working on `prd-foo`, then user asks about `prd-bar`? Finish `prd-foo`'s active turn first, drop its spec/techspec/tasks from active context, then load `prd-bar`. Never carry both spec sets.
+
+2. **Multiple archived bugfix SUMMARY.md files.** Bugfix history queries should go through `.dw/intel/bugfixes.json` (compact, indexed), not by reading 20 SUMMARY.md files. Read individual SUMMARY.md only when the user is acting on that specific fix.
+
+3. **Files.json + deps.json simultaneously.** They overlap. Each query has a primary file per `dw-codebase-intel/references/query-patterns.md`. Pick the primary; consult the secondary only if the primary returns nothing.
+
+4. **A design proposal AND its predecessor's full text.** When comparing two designs, summarize the older one to 5–10 lines (the deltas the new one addresses) and reference it that way. Don't carry both in full.
+
+5. **Per-task memories from non-adjacent tasks.** Only the current task's `<N>_memory.md` and the immediately-previous one (for handoff) belong in active context. Older `<N>_memory.md` files are durable storage — read them when explicitly handing back to an old task, not as part of routine loading.
+
+## The monitoring signal
+
+You will not see a token counter. You can't measure your own budget directly. But these are observable proxies that mean **you are over budget**:
+
+- You are reading the same file twice in the same session without it having changed.
+- You are summarizing the same fact across multiple turns to keep it in scope.
+- You are answering questions by re-deriving from the repo what a memory file would tell you in one line.
+- You are confusing details between two PRDs, tasks, or designs.
+- Your turn outputs are getting longer to compensate for context that is silently slipping out of the model's attention.
+
+When you notice any of these, stop:
+
+1. Compact `MEMORY.md` and the active `<N>_memory.md` per the Compaction Rules in `SKILL.md`.
+2. Explicitly state in chat what you are dropping from active context.
+3. Note the budget event in `MEMORY.md` under Handoff Notes ("compacted at task N — see this section for what was dropped").
+4. Resume the turn.
+
+## What is NOT a budget problem
+
+These look like budget problems but aren't — don't compact for them:
+
+- **A genuinely complex task.** Some features legitimately need many files. Read what you need; the alternative (working from partial context) is worse.
+- **A long verification report.** Verify output can be long. Don't summarize it before logging it to disk; truncate the chat surface, not the artifact.
+- **A long user message.** The user wrote what they wrote. Don't compact to shave their words.
+- **The first PRD load of a new feature.** First-load is fine; second-load of the same PRD in the same turn is the signal.
+
+## Integration with other skills
+
+- **`dw-memory` (this skill)**: compaction is the lever for memory files; this file describes when and why.
+- **`dw-codebase-intel`**: `query-patterns.md` defines the primary-vs-secondary rule that anti-co-load rule #3 references.
+- **`dw-verify`**: a budget-related degradation may show up as a verify regression. If verify keeps failing on facts the PRD already states, suspect budget before suspecting code.
+
+## Source
+
+Adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The 40k target, the anti-co-load principle, and the monitoring-signal framing come from there. The specific anti-co-load pairings, file-size ceilings, and the integration with `dw-memory`/`dw-codebase-intel` are dev-workflow-specific.