Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs: add Windsurf Issue Triage example doc (#414)

Muhammad Zeshan Malike8ebb587f037
diff --git a/examples/README.md b/examples/README.md
index a671065..c3b991c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -29,7 +29,7 @@ Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilit
| Post-Merge Cleanup | [grok/post-merge-cleanup.md](./grok/post-merge-cleanup.md) | [claude-code/post-merge-cleanup.md](./claude-code/post-merge-cleanup.md) | [codex/post-merge-cleanup.md](./codex/post-merge-cleanup.md) | [openclaw/post-merge-cleanup.md](./openclaw/post-merge-cleanup.md) | [cursor/post-merge-cleanup.md](./cursor/post-merge-cleanup.md) | — | [opencode/post-merge-cleanup.md](./opencode/post-merge-cleanup.md) | — | [github-actions/post-merge-cleanup.yml](./github-actions/post-merge-cleanup.yml) |
| Dependency Sweeper | [grok/dependency-sweeper.md](./grok/dependency-sweeper.md) | [claude-code/dependency-sweeper.md](./claude-code/dependency-sweeper.md) | [codex/dependency-sweeper.md](./codex/dependency-sweeper.md) | [openclaw/dependency-sweeper.md](./openclaw/dependency-sweeper.md) | [cursor/dependency-sweeper.md](./cursor/dependency-sweeper.md) | — | [opencode/dependency-sweeper.md](./opencode/dependency-sweeper.md) | — | [github-actions/dependency-sweeper.yml](./github-actions/dependency-sweeper.yml) |
| Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | [openclaw/changelog-drafter.md](./openclaw/changelog-drafter.md) | [cursor/changelog-drafter.md](./cursor/changelog-drafter.md) | — | [opencode/changelog-drafter.md](./opencode/changelog-drafter.md) | — | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) |
-| Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | [openclaw/issue-triage.md](./openclaw/issue-triage.md) | [cursor/issue-triage.md](./cursor/issue-triage.md) | — | [opencode/issue-triage.md](./opencode/issue-triage.md) | — | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) |
+| Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | [openclaw/issue-triage.md](./openclaw/issue-triage.md) | [cursor/issue-triage.md](./cursor/issue-triage.md) | [windsurf/issue-triage.md](./windsurf/issue-triage.md) | [opencode/issue-triage.md](./opencode/issue-triage.md) | — | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) |
L2 patterns ship multi-tool skills inside one starter folder — see `starters/<pattern>/`.
diff --git a/examples/windsurf/README.md b/examples/windsurf/README.md
index 71bbd7e..547deab 100644
--- a/examples/windsurf/README.md
+++ b/examples/windsurf/README.md
@@ -7,6 +7,7 @@ Copy-pasteable loop patterns for Windsurf, using Cascade Workflows as the manual
| Daily Triage | 1d–2h (manual `/daily-triage`) | Low | [daily-triage.md](daily-triage.md) |
| PR Babysitter | 5m–15m (manual `/pr-babysitter`; external reminder optional) | Medium | [pr-babysitter.md](pr-babysitter.md) |
| CI Sweeper | 5m–15m (manual `/ci-sweeper`; external reminder optional) | Medium | [ci-sweeper.md](ci-sweeper.md) |
+| Issue Triage | 2h–1d (manual `/issue-triage`; external reminder optional) | Low | [issue-triage.md](issue-triage.md) |
No `loop-init --tool windsurf` yet — copy `SKILL.md` + `STATE.md` from any starter (e.g. `starters/minimal-loop`), then follow the example to wire a Cascade Workflow.
diff --git a/examples/windsurf/issue-triage.md b/examples/windsurf/issue-triage.md
new file mode 100644
index 0000000..f386145
--- /dev/null
+++ b/examples/windsurf/issue-triage.md
@@ -0,0 +1,104 @@
+# Issue Triage — Windsurf (Cascade Workflows)
+
+This is a practical, copy-pasteable example of an Issue Triage loop using Windsurf's Cascade. Low-risk companion to [Daily Triage](./daily-triage.md). Keeps the issue queue legible so morning triage and humans always know the top five.
+
+Windsurf has no native `/loop` scheduler or built-in cron. Map the loop to a **Cascade Workflow** (`.windsurf/workflows/issue-triage.md`) and invoke it manually with `/issue-triage`; if you need an unattended cadence (e.g. 2h–1d), pair it with an external reminder or trigger (such as GitHub Actions cron, `launchd`, `cron`, or systemd) that prompts a human to run the workflow.
+
+## Setup
+
+Copy the shared skills and state into Windsurf's project-local paths:
+
+```bash
+mkdir -p .windsurf/rules/issue-triage \
+ .windsurf/rules/loop-verifier
+cp templates/SKILL.md.issue-triage \
+ .windsurf/rules/issue-triage/SKILL.md
+cp templates/SKILL.md.verifier \
+ .windsurf/rules/loop-verifier/SKILL.md
+cp starters/issue-triage/issue-triage-state.md.example \
+ issue-triage-state.md
+```
+
+Put always-on path denylists, label allowlists, and the no-auto-label rule in `.windsurf/rules/` as well as in the workflow prompt.
+
+## Workflow (week one — propose only)
+
+Create `.windsurf/workflows/issue-triage.md`:
+
+```markdown
+# Issue Triage
+
+**Description:** Discover open issues, propose priority (P0–P3) and labels, update state. Report only, no auto-apply or close.
+
+1. Read `issue-triage-state.md` and `.windsurf/rules/issue-triage/SKILL.md`.
+2. Scan open issues and discussions since the last run.
+3. Record top 5 prioritized items (P0–P3) with one-sentence summaries.
+4. Record suggested labels (proposed only — do not apply).
+5. Flag potential duplicates as "possible duplicate of #NNN" for human confirmation.
+6. Update `issue-triage-state.md` with evidence and human review items.
+7. Week one is propose-only:
+ - do not apply labels, close issues, or post comments;
+ - do not modify source files or workflow files;
+ - escalate P0/P1 issues touching security, auth, payments, or public APIs to a human.
+```
+
+Invoke in Cascade chat with `/issue-triage`.
+
+For an unattended cadence, keep Windsurf as the triage/review surface and use an external scheduler only to remind a human or trigger execution. Review the state file after every run. See [Safety and human gates](../../docs/safety.md) for permission boundaries.
+
+## Progression to L2 (auto-label allowlisted labels)
+
+After the propose-only output is consistently accurate (e.g. 10 stable L1 runs), enable auto-applying allowlisted labels:
+
+1. A human approves the allowlisted label scope (`area:*`, `needs-repro`, `needs-info`).
+2. Run `loop-verifier` (`.windsurf/rules/loop-verifier/SKILL.md`) in a separate session/verifier step over proposed label changes.
+3. Auto-apply only allowlisted labels after verifier passes.
+4. Never auto-apply P0, P1, security, or breaking-change labels. Never close or comment on issues without human approval.
+
+## Example `issue-triage-state.md`
+
+```markdown
+# Issue Triage State
+Last run: 2026-07-28 09:00 UTC
+Open actionable: 14 (was 17)
+New since last run: 3
+Needs human: 2
+
+## Top 5 (by loop score)
+
+- #487 (bug, p1, 2d old) — "Crash on export with large files" — suggested: bug, needs-repro, area:export
+- #491 (feature, p2) — "Dark mode for settings" — suggested: enhancement, area:ui
+- #488 (duplicate?) — possible duplicate of #412 — human confirm
+
+## Proposed Labels (not applied — L1)
+
+- #487: `bug`, `needs-repro`, `area:export`
+- #491: `enhancement`, `area:ui`
+
+## Possible Duplicates (human confirm)
+
+- #488: possible duplicate of #412
+
+## Noise / Ignored
+
+- (none)
+
+## Allowlisted labels (L2 only)
+
+`area:*`, `needs-repro`, `needs-info`
+
+## Denylist (always human)
+
+auth, payments, security, public-api, breaking-change
+```
+
+## Pairing with Daily Triage
+
+Issue Triage runs more frequently (2h–1d) and maintains a clean queue. Daily Triage (`/daily-triage`) reads `issue-triage-state.md` and merges top items into `STATE.md` High Priority.
+
+## References
+
+- [Issue Triage pattern](../../patterns/issue-triage.md)
+- [Issue Triage starter](../../starters/issue-triage/)
+- [Safety and human gates](../../docs/safety.md)
+- [Primitives matrix](../../docs/primitives-matrix.md#appendix-editor-transfer-recipes-opencode-cursor--windsurf)
diff --git a/patterns/registry.yaml b/patterns/registry.yaml
index bf3942a..c145571 100644
--- a/patterns/registry.yaml
+++ b/patterns/registry.yaml
@@ -140,7 +140,7 @@ patterns:
goal: Discover, deduplicate, prioritize and label incoming issues/discussions so the team always has a clean actionable queue. Excellent low-risk companion to Daily Triage.
cadence: 2h-1d
risk: low
- tools: [grok, claude-code, codex, openclaw, opencode, github-actions]
+ tools: [grok, claude-code, codex, openclaw, opencode, github-actions, windsurf]
skills: [issue-triage, loop-verifier]
state: issue-triage-state.md
phases: [discover, dedupe, score, propose-labels, human-review]