@brunosps00/dev-workflow 2.0.0 → 2.1.0

package/scaffold/en/commands/dw-triage.md

@@ -0,0 +1,220 @@
+<system_instructions>
+You are the intake triage boundary for the current workspace. Your job is to receive external work requests, verify them against the codebase, decide their disposition with the owner, persist the triage state in `.dw/`, and only then route into the existing dev-workflow pipeline.
+
+<critical>`/dw-triage` sits BEFORE `/dw-bugfix`, `/dw-brainstorm`, `/dw-plan`, and `/dw-run`. It does not replace any of them.</critical>
+<critical>Local-first: `.dw/triage/**` is the durable source of truth. GitHub access via `gh` is optional enrichment only.</critical>
+<critical>Never write a downstream brief from an unverified allegation. Verification is the point of this command.</critical>
+
+## When to Use
+- Use when an external bug report, feature request, support escalation, issue, or PR arrives and needs an intake decision before normal planning or execution
+- Use when the request might be redundant, previously rejected, underspecified, or needs a human decision before it enters the pipeline
+- Do NOT use to fix an already accepted bug directly; use `/dw-bugfix`
+- Do NOT use to plan an already accepted enhancement directly; use `/dw-plan prd`
+- Do NOT use for vague ideation with no intake item; use `/dw-brainstorm`
+
+## Pipeline Position
+**Predecessor:** external request (paste, file, issue, PR) | **Successor:** `/dw-brainstorm --mode=grill`, `/dw-bugfix`, `/dw-plan prd`, `/dw-run`, or no downstream action
+
+## Inputs
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{SOURCE}}` | Request source: pasted text, local file path, issue/PR URL, issue/PR number, or branch/ref | `.dw/inbox/report.md`, `#123`, `https://github.com/org/repo/pull/42` |
+| `{{MODE}}` | Optional owner intent | `--bug`, `--enhancement`, `--pr`, `--offline`, `--no-github-write` |
+
+## File Locations
+
+**Triage record — always created after owner-approved disposition:**
+
+- `.dw/triage/NNN-<slug>.md`
+- `NNN` is zero-padded to 3 digits, sequential across every triage record ever created
+- `<slug>` is kebab-case from the domain concept, not merely the request wording
+- Use `.dw/templates/triage-record-template.md`
+
+This follows the `.dw/bugfixes/NNN-<slug>/` index precedent: intake records are chronological workflow records, so they need stable ordering. A single markdown file is enough because triage has one state document; downstream work owns its own directories.
+
+**Needs-info notes:**
+
+- Stored inside the same `.dw/triage/NNN-<slug>.md` record under `## Needs Info`
+- Use `.dw/templates/triage-needs-info-template.md` as the section body when questions are open
+
+**Out-of-scope memory — only for rejected concepts:**
+
+- `.dw/out-of-scope/<concept>.md`
+- `<concept>` is a stable domain concept slug, not a quote of the request
+- Use `.dw/templates/triage-out-of-scope-template.md`
+- Do NOT write `.dw/out-of-scope/**` for "already implemented"; point to the existing implementation instead
+
+**Next-number discovery:** list `.dw/triage/`, parse the leading 3-digit prefix of each `*.md`, take `max + 1` or `1` if empty.
+
+## State Model
+
+Every triage item carries exactly one category and exactly one state.
+
+Categories:
+- `bug`
+- `enhancement`
+
+States:
+- `needs-triage`
+- `needs-info`
+- `ready-for-work`
+- `needs-human`
+- `wontfix`
+
+Transitions:
+- `needs-triage` -> `needs-info`
+- `needs-triage` -> `ready-for-work`
+- `needs-triage` -> `needs-human`
+- `needs-triage` -> `wontfix`
+- `needs-info` -> `needs-triage` when the author responds
+
+If the current record, source labels, or owner input imply conflicting states, STOP and ask the owner which single state is authoritative before writing or routing.
+
+Vocabulary note: upstream uses `ready-for-agent` / `ready-for-human`. In dev-workflow the accepted implementation lane is `/dw-run`, fed by `/dw-bugfix` or `/dw-plan`, so this command uses `ready-for-work` for "pipeline-ready" and `needs-human` for work that cannot be delegated safely.
+
+## GitHub Integration
+
+`gh` is allowed because this repo already uses it in `/dw-generate-pr`, but it is never required.
+
+1. If `{{SOURCE}}` is a GitHub issue/PR URL or number, check whether `gh` exists and whether `git remote -v` points at GitHub.
+2. If both checks pass, you may read the issue/PR with `gh issue view` or `gh pr view`, and for PRs read the diff with `gh pr diff`.
+3. If `gh` is missing, unauthenticated, offline, or the remote is not GitHub, continue from the pasted text, local file, or explicit argument. If the necessary issue text or PR diff is not available locally, ask the owner to paste it or provide a file path.
+4. Do not mention Linear, Jira, GitLab, or any tracker-specific behavior as supported integration. The source is pluggable later; this command only defines local files plus optional GitHub read enrichment.
+5. Never comment, close, label, or otherwise write back to GitHub unless the owner explicitly opts in for that exact write. Triage persistence in `.dw/triage/**` is the default and sufficient output.
+
+## Workflow
+
+### 1. Read the Complete Request
+
+- Read the full pasted text or local file.
+- If the source is an issue and `gh` is available, read the title, body, comments, labels, author, and URL.
+- If the source is a PR and `gh` is available, read the title, body, comments, changed files, and diff.
+- Preserve the origin in the triage record: `source_type`, `source_ref`, `author`, `reported_at`, and retrieval method.
+
+### 2. Check Redundancy Before Recommending
+
+Search by domain concept, not wording:
+
+- `.dw/domain/**` when present
+- `.dw/spec/**`
+- `.dw/bugfixes/**`
+- `.dw/rules/**`
+- code paths likely to own the concept
+- docs and tests that name the behavior
+
+If equivalent behavior already exists, recommend `wontfix` with reason `already implemented`, report exactly where you searched and where the implementation lives, write the triage record, and do NOT write `.dw/out-of-scope/**`.
+
+### 3. Check Prior Rejections
+
+Read `.dw/out-of-scope/**` when it exists. Surface any similar domain concept before recommending a state:
+
+```
+## Prior Rejection Found
+
+- Concept: `<concept>`
+- Record: `.dw/out-of-scope/<concept>.md`
+- Why it matters: <one-line comparison>
+```
+
+If the prior rejection clearly applies, recommend `wontfix` unless the owner explicitly reopens the decision.
+
+### 4. Recommend Category And State, Then Wait
+
+Present:
+
+- concise summary of the request
+- codebase search summary, including where redundancy was checked
+- prior rejection summary
+- recommended category: `bug` or `enhancement`
+- recommended state: `needs-info`, `ready-for-work`, `needs-human`, or `wontfix`
+- reasoning and next route
+
+Then ask the owner to approve or correct the category/state. Do not write files or route downstream until the owner answers, unless an existing approved triage record is being resumed.
+
+### 5. Verify Before Briefing
+
+After owner approval and before any downstream brief:
+
+**For bugs:**
+- Reproduce from the author's steps when possible.
+- Record the exact command, environment, fixture, or manual path used.
+- Report one result: `confirmed`, `failed-to-reproduce`, or `insufficient-detail`.
+- Treat `insufficient-detail` as a strong signal for `needs-info`.
+
+**For PRs:**
+- Confirm the diff does what the PR claims.
+- Run relevant tests or checks for the touched area.
+- Record the changed files inspected and commands run.
+- If the claim and diff disagree, stop and recommend `needs-human` or `needs-info`.
+
+**For enhancements:**
+- Verify the capability does not already exist and that the request has enough product shape for PRD intake.
+- If the product vocabulary or desired outcome is unsettled, route to `/dw-brainstorm --mode=grill` instead of inventing an interview here.
+
+### 6. Apply The Outcome
+
+Use `.dw/templates/triage-record-template.md` for every written triage item. Record history entries as `YYYY-MM-DD — <from> -> <to> — <actor> — <reason>`.
+
+Outcomes:
+
+- `ready-for-work` + `bug` -> write `.dw/triage/NNN-<slug>.md`, then route to `/dw-bugfix` with the verified reproduction summary and triage record path
+- `ready-for-work` + `enhancement` -> write `.dw/triage/NNN-<slug>.md`, then route to `/dw-plan prd` with the verified product summary and triage record path
+- `needs-human` -> write `.dw/triage/NNN-<slug>.md` and record why delegation is unsafe: design decision, external access, judgment call, manual test, or unclear ownership
+- `needs-info` -> write `.dw/triage/NNN-<slug>.md` and include the `.dw/templates/triage-needs-info-template.md` section with open questions
+- `wontfix` rejected -> write `.dw/triage/NNN-<slug>.md`, then write or update `.dw/out-of-scope/<concept>.md` with the reason, evidence, and revisit condition
+- `wontfix` already implemented -> write `.dw/triage/NNN-<slug>.md`, point to the implementation, and do NOT write `.dw/out-of-scope/**`
+
+### 7. Grill Malformed Requests
+
+If the request lacks a stable problem, actor, domain concept, desired outcome, or acceptance boundary, do not reimplement an interview inside `/dw-triage`.
+
+Recommend:
+
+```
+This intake item is not ready to categorize. Route to `/dw-brainstorm --mode=grill` to settle the product vocabulary and boundaries, then return to `/dw-triage` when the author answers.
+```
+
+If the owner approves the route, persist the triage record as `needs-info` unless there is a clearer `needs-human` reason.
+
+## Preferred Response Format
+
+### Intake Summary
+- Source:
+- Request:
+- Author:
+- Retrieval:
+
+### Codebase Checks
+- Redundancy search:
+- Prior rejection search:
+- Evidence:
+
+### Recommendation
+- Category: `bug` | `enhancement`
+- State: `needs-info` | `ready-for-work` | `needs-human` | `wontfix`
+- Reason:
+- Proposed route:
+
+### Owner Checkpoint
+- Ask the owner to approve or correct the category/state before writing and routing.
+
+### Verification Result
+- Status: `confirmed` | `failed-to-reproduce` | `insufficient-detail`
+- Commands/files inspected:
+- What this proves:
+
+### Persisted Outcome
+- Triage record:
+- Out-of-scope record, if any:
+- Next command:
+
+## Anti-patterns
+
+- Treating GitHub labels or comments as the source of truth
+- Creating `.dw/out-of-scope/**` for an already implemented request
+- Matching redundancy only by request wording
+- Routing to `/dw-bugfix` or `/dw-plan prd` before owner approval
+- Writing a bugfix or PRD brief from an unverified claim
+- Promising tracker integrations this command cannot actually read or write
+</system_instructions>

package/scaffold/en/templates/idea-onepager.md

@@ -93,6 +93,34 @@ Ideally 2-4 stories. If it's more than 5, it's probably not MVP.]
 
 _(schema 1.1 — filled by a `/dw-brainstorm` grill session; consumed by `/dw-plan`, which does NOT re-ask resolved decisions. Leave empty for a non-grilled one-pager.)_
 
+### Decision Map
+
+[Durable Grill tree. This records structure and resume state only; keep the decision outcome, recommendation,
+alternative, and evidence in **Resolved Decisions** below.]
+
+**Frontier:** [comma-separated node IDs with `State: open-ready`, or `none`]
+
+| ID | Decision node | State | Depends on: | Frontier? | Notes |
+|----|---------------|-------|-------------|-----------|-------|
+| D1 | [upstream decision] | resolved | none | no | [structure note; outcome lives in Resolved Decisions] |
+| D2 | [open decision that can be asked next] | open-ready | D1 | yes | [why this is ready] |
+| D3 | [open decision still blocked] | open-blocked | D2 | no | [what blocks it] |
+
+`State` is the source of truth. `Frontier?` and the `**Frontier:**` line are derived from it for
+readability — if they ever disagree with `State`, `State` wins and the derived values are rewritten.
+
+Allowed `State` values:
+- `resolved` — the user settled the node; details live in **Resolved Decisions**.
+- `open-ready` — open and decidable now; this node is in the **Frontier**.
+- `open-blocked` — open but waiting on one or more `Depends on:` nodes.
+
+#### Decision Fog
+
+[Known unresolved areas that are not yet clear enough to phrase as decision nodes. Keep this short; each item
+graduates into **Decision Map** when it becomes a concrete decision.]
+
+- [unknown area] — [why it is not yet formulable as a decision]
+
 ### Resolved Decisions
 
 | Decision | Recommended | Chosen | Alternative rejected | Evidence |

package/scaffold/en/templates/task-template.md

@@ -13,6 +13,7 @@ status: pending
 [Brief task description]
 
 **Functional Requirements covered**: FR-X.Y, FR-X.Z (maximum 2 per task)
+Depends on: none
 
 <requirements>
 [List of mandatory requirements]

package/scaffold/en/templates/tasks-template.md

@@ -19,19 +19,20 @@ feat/prd-[feature-name]
 
 ## Tasks
 
-| Task | Description | FRs | Status | Commit |
-|------|-------------|-----|--------|--------|
-| 1.0 | [Title] | FR-1.1, FR-1.2 | Pending | — |
-| 2.0 | [Title] | FR-2.1 | Pending | — |
-| 3.0 | [Title] | FR-3.1, FR-3.2 | Pending | — |
+| Task | Description | Depends on | FRs | Status | Commit |
+|------|-------------|------------|-----|--------|--------|
+| 1.0 | [Title] | none | FR-1.1, FR-1.2 | Pending | — |
+| 2.0 | [Title] | 1.0 | FR-2.1 | Pending | — |
+| 3.0 | [Title] | 1.0, 2.0 | FR-3.1, FR-3.2 | Pending | — |
 
 `Commit` holds the short SHA written back by `/dw-run` when the task closes (step 6). It is what makes a task's diff findable later — leave `—` until the task commits.
+`Depends on` is the dependency graph consumed by `/dw-run`; write `none` when a task has no dependency.
 
 ## Progress
 
-- [ ] 1.0 Main Task Title
-- [ ] 2.0 Main Task Title
-- [ ] 3.0 Main Task Title
+- [ ] 1.0 Main Task Title        Depends on: none
+- [ ] 2.0 Main Task Title        Depends on: 1.0
+- [ ] 3.0 Main Task Title        Depends on: 1.0, 2.0
 
 ## Workflow
 

package/scaffold/en/templates/triage-needs-info-template.md

@@ -0,0 +1,23 @@
+# Needs Info: <title>
+
+## Blocking Questions
+
+- [ ] <question 1>
+- [ ] <question 2>
+- [ ] <question 3>
+
+## Why This Blocks Triage
+
+<Explain why the missing information prevents category/state confidence or verification.>
+
+## Author Response
+
+<Paste or summarize the author's response. When the author responds, move the triage state from `needs-info` to `needs-triage` and re-run the recommendation step.>
+
+## Requested Evidence
+
+- Reproduction steps:
+- Expected vs actual behavior:
+- Environment or test data:
+- PR diff or branch/ref:
+- Screenshots/logs/traces:

package/scaffold/en/templates/triage-out-of-scope-template.md

@@ -0,0 +1,36 @@
+---
+type: out-of-scope
+schema_version: "1.0"
+concept: "<concept-slug>"
+created_at: "YYYY-MM-DD"
+updated_at: "YYYY-MM-DD"
+---
+
+# Out of Scope: <Concept Name>
+
+## Decision
+
+Rejected on YYYY-MM-DD.
+
+## Reason
+
+<Record the durable reason. Do not write only "wontfix"; explain the product, technical, operational, or policy boundary.>
+
+## Applies To
+
+- <Domain phrasing of requests this decision covers>
+- <Known alternate wording that maps to the same concept>
+
+## Evidence
+
+- Triage record: `.dw/triage/NNN-<slug>.md`
+- Codebase search:
+- Prior decisions:
+
+## Revisit Conditions
+
+<What would need to change for this concept to be reconsidered?>
+
+## History
+
+- YYYY-MM-DD — rejected — <actor> — <reason>

package/scaffold/en/templates/triage-record-template.md

@@ -0,0 +1,88 @@
+---
+type: triage-record
+schema_version: "1.0"
+id: "NNN-<slug>"
+category: "bug | enhancement"
+state: "needs-triage | needs-info | ready-for-work | needs-human | wontfix"
+created_at: "YYYY-MM-DD"
+updated_at: "YYYY-MM-DD"
+---
+
+# Triage: <title>
+
+## Source
+
+| Field | Value |
+|-------|-------|
+| Source Type | paste / file / github-issue / github-pr / other |
+| Source Ref | <path, URL, issue number, PR number, or pasted-session marker> |
+| Author | <name or unknown> |
+| Reported At | <date or unknown> |
+| Retrieved By | local / gh / pasted / owner-provided |
+
+## Intake Summary
+
+<Short summary of the request in domain language.>
+
+## Classification
+
+| Field | Value |
+|-------|-------|
+| Category | bug / enhancement |
+| State | needs-triage / needs-info / ready-for-work / needs-human / wontfix |
+| Domain Concept | <concept slug and human name> |
+| Disposition Reason | <why this state was chosen> |
+
+## Codebase Checks
+
+### Redundancy Search
+
+| Area Searched | Query / Concept | Result |
+|---------------|-----------------|--------|
+| `.dw/domain/**` | <concept> | <match / no match / missing> |
+| `.dw/spec/**` | <concept> | <match / no match / missing> |
+| `.dw/bugfixes/**` | <concept> | <match / no match / missing> |
+| `.dw/rules/**` | <concept> | <match / no match / missing> |
+| Code / tests / docs | <concept> | <match / no match> |
+
+### Prior Rejection Search
+
+| Record | Similarity | Decision |
+|--------|------------|----------|
+| `.dw/out-of-scope/<concept>.md` | <why similar> | applies / does not apply / reopened |
+
+## Verification
+
+| Field | Value |
+|-------|-------|
+| Verification Status | confirmed / failed-to-reproduce / insufficient-detail |
+| Verification Method | reproduce steps / PR diff review / relevant tests / product inventory check |
+| Commands Run | <commands or n/a> |
+| Files Inspected | <paths> |
+| Evidence | <what was observed> |
+
+## Needs Info
+
+<!-- If state is needs-info, paste the body from triage-needs-info-template.md here. Otherwise write "n/a". -->
+
+n/a
+
+## Routing
+
+| Condition | Route |
+|-----------|-------|
+| ready-for-work + bug | `/dw-bugfix` |
+| ready-for-work + enhancement | `/dw-plan prd` |
+| malformed request | `/dw-brainstorm --mode=grill` |
+| needs-human | owner action |
+| wontfix | no downstream work |
+
+Selected route: <route or n/a>
+
+## Out-of-Scope Link
+
+<If rejected, link `.dw/out-of-scope/<concept>.md`. If already implemented, link the implementation and state that no out-of-scope record was written.>
+
+## History
+
+- YYYY-MM-DD — needs-triage -> <state> — <actor> — <reason>