docs: document Tasks API field visibility limitations (Gang Rui analysis)
Integration of community practitioner feedback on Tasks API (v2.1.16+) field visibility constraints discovered through real-world usage. Changes: - guide/ultimate-guide.md: * Added 3 rows to comparison table (field visibility, metadata, overhead) * New subsection "⚠️ Tasks API Limitations (Critical)" (~40 lines) * Field visibility constraint table, cost examples, 3 workaround patterns - guide/workflows/task-management.md: * New subsection "⚠️ Field Visibility Limitations" (~35 lines) * Workflow adjustments, cost awareness, mitigation strategies - guide/cheatsheet.md: * Added limitation note with actionable tip (~3 lines) - machine-readable/reference.yaml: * 4 new entries: limitations, field_visibility, cost_overhead, workarounds * Updated resource_evaluations_count: 16 → 22 - docs/resource-evaluations/016-gang-rui-tasks-api-limitations.md: * New comprehensive evaluation (score 5/5 CRITICAL) * Fact-check, challenge phase, integration details - README.md: * Updated resource evaluations count: 15 → 22 assessments Score: 5/5 (CRITICAL) - Breaks recommended workflow, 11x-51x cost overhead, prevents user frustration, maintains guide credibility. Source: https://www.linkedin.com/posts/limgangrui_i-explored-the-new-claude-codes-task-system-activity-7420651412881268736-Hpd6 Date: 2026-01-24 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
edf74b38c5
commit
3a5012eef7
7 changed files with 493 additions and 10 deletions
|
|
@ -220,6 +220,42 @@ Tasks survive:
|
|||
- System restarts
|
||||
- Multiple days of interruption
|
||||
|
||||
#### ⚠️ Field Visibility Limitations
|
||||
|
||||
**TaskList returns only**: `id`, `subject`, `status`, `owner`, `blockedBy`
|
||||
|
||||
**Missing in TaskList output**:
|
||||
- `description` (requires TaskGet per task)
|
||||
- `metadata` (custom fields like priority, estimates)
|
||||
- `activeForm` (progress spinner text)
|
||||
|
||||
**Workflow adjustment**:
|
||||
|
||||
```bash
|
||||
# DON'T: Assume you can scan all descriptions
|
||||
TaskList # Shows subjects only
|
||||
|
||||
# DO: Fetch selectively
|
||||
TaskList # Get overview (which tasks exist, statuses)
|
||||
TaskGet(task-auth-login) # Get full details for specific task
|
||||
TaskGet(task-auth-tests) # Get details for next task
|
||||
```
|
||||
|
||||
**When this matters**:
|
||||
- Complex projects with detailed task descriptions (>50 words per task)
|
||||
- Multi-agent coordination requiring shared context visibility
|
||||
- Need to quickly scan all task notes to decide resumption point
|
||||
|
||||
**Cost awareness**:
|
||||
- TaskList = 1 API call
|
||||
- Fetching descriptions for N tasks = 1 + N calls
|
||||
- For 20 tasks, that's 20x overhead if you need all descriptions
|
||||
|
||||
**Mitigation**:
|
||||
- Use `subject` field for critical info (visible in TaskList)
|
||||
- Keep `description` concise (50-100 words max)
|
||||
- Store detailed plans in markdown files (`docs/plan-*.md`)
|
||||
|
||||
### Resume Pattern
|
||||
|
||||
```bash
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue