Skip to content

Commit 8cfb7a4

Browse files
claudeclaude
committed
Docs: all MCP tools, DartQL reference, cookbook with 16 recipes
- Document all 25 MCP tools across 7 grouped pages (discovery, task mgmt, query, batch ops, documents, import, workspace) - DartQL syntax reference: SQL-92 operators, fields, performance notes - DartQL selectors guide: LIKE patterns, CONTAINS, relationships, IN/NOT IN - Cookbook: 16 copy-paste recipes for sprint mgmt, cleanup, reporting, relationships, CSV Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c476c81 commit 8cfb7a4

10 files changed

Lines changed: 1734 additions & 17 deletions

File tree

‎docs/src/content/docs/cookbook/recipes.mdx‎

Lines changed: 262 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,267 @@
11
---
2-
title: Common Recipes
3-
description: Practical examples for common dart-query workflows.
2+
title: "DartQL Recipes"
3+
description: Copy-paste DartQL recipes for bulk task updates, batch task management, sprint planning, cleanup, and AI project management automation.
44
sidebar:
55
order: 1
66
---
77

8-
Content coming soon.
8+
Practical DartQL recipes you can copy, adapt, and run. Each recipe uses `execute_dartql`, the preferred tool for batch operations. Always start with `dry_run: true` (the default) to preview before executing.
9+
10+
## Sprint Management
11+
12+
### How to Bulk Update Task Status
13+
14+
Move all in-progress tasks to done at the end of a sprint:
15+
16+
```sql
17+
UPDATE WHERE dartboard = 'Engineering/sprint-12' AND status = 'Doing'
18+
SET status = 'Done'
19+
COMMENT 'Sprint 12 closed: {title}'
20+
```
21+
22+
**Tip:** The `{title}` template variable inserts each task's title into the comment automatically.
23+
24+
### Bulk-Assign Tasks to a Team Member
25+
26+
Assign all unassigned high-priority backend tasks to a specific engineer:
27+
28+
```sql
29+
UPDATE WHERE dartboard = 'Engineering/backend'
30+
AND priority = 'high'
31+
AND assignee IS NULL
32+
SET assignees = ['engineer@company.com']
33+
```
34+
35+
### Set Sprint Deadlines in Batch
36+
37+
Apply a due date to all tasks in the current sprint that don't have one:
38+
39+
```sql
40+
UPDATE WHERE dartboard = 'Engineering/sprint-13'
41+
AND due_at IS NULL
42+
SET due_at = '2026-02-14T00:00:00Z'
43+
```
44+
45+
### Reprioritize Overdue Tasks
46+
47+
Escalate overdue tasks that are still open:
48+
49+
```sql
50+
UPDATE WHERE due_at < '2026-04-09T00:00:00Z'
51+
AND status != 'Done'
52+
AND priority = 'high'
53+
SET priority = 'critical'
54+
COMMENT 'Auto-escalated: overdue'
55+
```
56+
57+
## Cleanup and Archival
58+
59+
### Archive Completed Tasks by Quarter
60+
61+
Move all tasks completed in Q1 to an archive dartboard:
62+
63+
```sql
64+
UPDATE WHERE completed_at >= '2026-01-01T00:00:00Z'
65+
AND completed_at < '2026-04-01T00:00:00Z'
66+
SET dartboard = 'Archive/2026-Q1'
67+
```
68+
69+
**Tip:** Use `concurrency: 10` for large batches to speed up execution.
70+
71+
### Delete Stale Low-Priority Tasks
72+
73+
Remove tasks that haven't been updated in months and are still in the backlog:
74+
75+
```sql
76+
DELETE WHERE priority = 'low'
77+
AND updated_at < '2025-10-01T00:00:00Z'
78+
AND status = 'To Do'
79+
CONFIRM
80+
```
81+
82+
**Safety:** The `CONFIRM` keyword is required for DELETE statements when `dry_run` is false. Without it, the statement is rejected.
83+
84+
### Find and Remove Duplicate Tasks
85+
86+
Find tasks marked as duplicates and delete them:
87+
88+
```sql
89+
DELETE WHERE duplicate_ids IS NOT NULL CONFIRM
90+
```
91+
92+
### Multi-Statement Cleanup
93+
94+
Archive done tasks and delete abandoned ones in a single call:
95+
96+
```sql
97+
UPDATE WHERE status = 'Done' AND dartboard = 'Engineering/backend'
98+
SET dartboard = 'Archive/2026-Q1';
99+
DELETE WHERE status = 'To Do'
100+
AND updated_at < '2025-07-01T00:00:00Z'
101+
AND priority = 'low'
102+
CONFIRM
103+
```
104+
105+
**Tip:** Semicolons separate statements. Each runs independently, so a failure in one does not block the others.
106+
107+
## Reporting and Filtering
108+
109+
### Find All Blocked Tasks
110+
111+
Use `list_tasks` or `batch_update_tasks` with `dry_run: true` to query without changing anything:
112+
113+
```sql
114+
UPDATE WHERE blocker_ids IS NOT NULL
115+
SET tags = ['blocked-review']
116+
```
117+
118+
Run this as a dry run first to see which tasks have blockers. If you want to tag them for tracking, execute with `dry_run: false`.
119+
120+
### Filter Tasks by Date Range
121+
122+
Find tasks created during a specific period:
123+
124+
```sql
125+
UPDATE WHERE created_at BETWEEN '2026-03-01T00:00:00Z' AND '2026-03-31T23:59:59Z'
126+
SET tags = ['march-audit']
127+
```
128+
129+
### Find Unassigned Critical Tasks
130+
131+
Identify critical tasks with no owner:
132+
133+
```sql
134+
UPDATE WHERE priority = 'critical'
135+
AND assignee IS NULL
136+
SET tags = ['needs-owner']
137+
```
138+
139+
### Search by Title Pattern
140+
141+
Find tasks matching a keyword pattern:
142+
143+
```sql
144+
UPDATE WHERE title LIKE '%authentication%'
145+
AND status != 'Done'
146+
SET tags = ['auth-related']
147+
```
148+
149+
**Tip:** `LIKE` uses SQL-92 wildcards: `%` matches any characters, `_` matches a single character. Matching is case-insensitive.
150+
151+
## Relationship Management
152+
153+
### Set Up Release Blockers
154+
155+
Mark critical tasks as blocking a release:
156+
157+
```sql
158+
UPDATE WHERE priority = 'critical' AND status != 'Done'
159+
SET blocking_ids = ['duid_release_v2']
160+
```
161+
162+
**Important:** Relationship arrays use full replacement. This sets `blocking_ids` to exactly the value provided, replacing any previous values.
163+
164+
### Clear All Blockers from a Dartboard
165+
166+
Unblock all tasks in a dartboard after a dependency ships:
167+
168+
```sql
169+
UPDATE WHERE dartboard = 'Engineering/frontend'
170+
AND blocker_ids IS NOT NULL
171+
SET blocker_ids = []
172+
```
173+
174+
**Tip:** An empty array `[]` clears all relationships of that type.
175+
176+
### Link Security Tasks to an Audit
177+
178+
Tag and link all security-related tasks to an audit tracker:
179+
180+
```sql
181+
UPDATE WHERE tags CONTAINS 'security'
182+
SET related_ids = ['duid_security_audit_2026'],
183+
priority = 'critical'
184+
```
185+
186+
### Find Parent Tasks with Subtasks
187+
188+
Identify tasks that have children:
189+
190+
```sql
191+
UPDATE WHERE subtask_ids IS NOT NULL
192+
AND tags CONTAINS 'epic'
193+
SET tags = ['epic', 'has-subtasks']
194+
```
195+
196+
### Find Tasks Blocked by a Specific Task
197+
198+
Query which tasks depend on a particular blocker:
199+
200+
```sql
201+
UPDATE WHERE blocker_ids CONTAINS 'duid_infra_migration'
202+
SET tags = ['awaiting-infra']
203+
```
204+
205+
## CSV Import Workflows
206+
207+
### Import Tasks from a Spreadsheet
208+
209+
Use `import_tasks_csv` with column mapping to create tasks from a CSV file:
210+
211+
```typescript
212+
// Step 1: Validate without creating anything
213+
import_tasks_csv({
214+
csv_file_path: "./backlog.csv",
215+
dartboard: "Engineering/backend",
216+
column_mapping: {
217+
"Summary": "title",
218+
"Details": "description",
219+
"Owner Email": "assignee",
220+
"Priority Level": "priority",
221+
"Labels": "tags"
222+
},
223+
validate_only: true
224+
})
225+
226+
// Step 2: Review validation results, then import
227+
import_tasks_csv({
228+
csv_file_path: "./backlog.csv",
229+
dartboard: "Engineering/backend",
230+
column_mapping: {
231+
"Summary": "title",
232+
"Details": "description",
233+
"Owner Email": "assignee",
234+
"Priority Level": "priority",
235+
"Labels": "tags"
236+
},
237+
validate_only: false
238+
})
239+
```
240+
241+
**Tip:** Always call `get_config()` first to see valid dartboard names, priorities, and statuses for your workspace.
242+
243+
### Import and Tag for Tracking
244+
245+
After importing, tag the batch so you can manage them together:
246+
247+
```sql
248+
UPDATE WHERE dartboard = 'Engineering/backend'
249+
AND tags CONTAINS 'imported'
250+
SET priority = 'medium'
251+
```
252+
253+
Add an `imported` tag column in your CSV, or use the `default_values` parameter during import to auto-tag.
254+
255+
## Performance Tips
256+
257+
- **API-compatible selectors are faster.** Simple `=` on `assignee`, `status`, `dartboard`, `priority`, and `tags` goes directly to the Dart API. Complex operators like `OR`, `LIKE`, `IN`, and `BETWEEN` require client-side filtering (fetches all tasks first).
258+
- **Use `concurrency`** to control throughput. Default is 5; increase to 10-20 for large batches, decrease to 1-2 if hitting rate limits.
259+
- **Dry run first, always.** `dry_run: true` is the default. Preview your selector matches before executing any mutation.
260+
- **Multi-statement batches** run statements sequentially. Put the most important operation first.
261+
262+
## Next Steps
263+
264+
- [DartQL Syntax](/dart-query/dartql/syntax/) -- full operator and field reference
265+
- [Batch Operations](/dart-query/tools/batch-operations/) -- tool schemas and output formats
266+
- [Relationships](/dart-query/features/relationships/) -- managing blockers, subtasks, and related tasks
267+
- [CSV Import](/dart-query/features/csv-import/) -- detailed import options and field mapping

0 commit comments

Comments
 (0)