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>
2026-01-27 16:16:49 +01:00 · 2026-01-27 16:16:49 +01:00 · 3a5012eef7
commit 3a5012eef7
parent edf74b38c5
7 changed files with 493 additions and 10 deletions
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@ -396,6 +396,11 @@ claude
 - 🔄 **Multi-session**: Broadcast state to multiple terminals
 - 📊 **Status**: pending → in_progress → completed/failed

+**⚠️ Limitation**: TaskList shows `id`, `subject`, `status`, `blockedBy` only.
+For `description`/`metadata` → use `TaskGet(taskId)` per task.
+
+**Tip**: Store key info in `subject` for quick scanning.
+
 **Migration flag** (v2.1.19+):
 ```bash
 # Revert to old TodoWrite system
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@ -3137,6 +3137,9 @@ Claude Code provides two task management approaches:
 | **Dependencies** | ❌ Manual ordering | ✅ Task blocking (A blocks B) |
 | **Coordination** | Single agent | ✅ Multi-agent broadcast |
 | **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed |
+| **Description visibility** | ✅ Always visible | ⚠️ TaskGet only (not in TaskList) |
+| **Metadata visibility** | N/A | ❌ Never visible in outputs |
+| **Multi-call overhead** | None | ⚠️ 1 + N calls for N full tasks |
 | **Enabled by** | Always available | Default since v2.1.19 |

 #### Tasks API (v2.1.16+)
@ -3191,6 +3194,47 @@ claude
 - Multi-agent coordination scenarios
 - Need to resume work after context compaction

+**⚠️ Tasks API Limitations (Critical)**
+
+**Field visibility constraint**:
+
+| Tool | Visible Fields | Hidden Fields |
+|------|----------------|---------------|
+| `TaskList` | `id`, `subject`, `status`, `owner`, `blockedBy` | `description`, `activeForm`, `metadata` |
+| `TaskGet` | All fields | - |
+
+**Impact**:
+- **Multi-call overhead**: Reviewing 10 task descriptions = 1 TaskList + 10 TaskGet calls (11x overhead)
+- **No metadata scanning**: Cannot filter/sort by custom fields (priority, estimates, tags) without fetching all tasks individually
+- **Session resumption friction**: Cannot glance at all task notes to decide where to resume
+
+**Cost example**:
+```bash
+# Inefficient (if you need descriptions)
+TaskList  # Returns 10 tasks (no descriptions)
+TaskGet(task-1), TaskGet(task-2), ..., TaskGet(task-10)  # 10 additional calls
+
+# Total: 11 API calls to review 10 tasks
+```
+
+**Workaround patterns**:
+
+1. **Hybrid approach** (Recommended):
+   - Use Tasks API for **status tracking** and **dependency coordination**
+   - Maintain markdown files in repo for **detailed implementation plans**
+   - Example: `docs/plans/auth-refactor.md` + Tasks for status
+
+2. **Subject-as-summary pattern**:
+   - Store critical info in `subject` field (always visible in TaskList)
+   - Keep `description` for deep context (fetch on-demand with TaskGet)
+   - Example subjects: `"[P0] Fix login bug (src/auth.ts:45)"` vs `"Fix bug"`
+
+3. **Selective fetching**:
+   - Use TaskList to identify tasks needing attention (status, blockedBy)
+   - Only call TaskGet for tasks you're actively working on
+
+**Source**: Community practitioner feedback ([Gang Rui, Jan 2026](https://www.linkedin.com/posts/limgangrui_i-explored-the-new-claude-codes-task-system-activity-7420651412881268736-Hpd6))
+
 #### TodoWrite (Legacy)

 **Tool**: `TodoWrite` - Creates task lists stored in session memory
@ -14763,6 +14807,29 @@ SuperClaude transforms Claude Code into a structured development platform throug
 - Task management and session persistence
 - **Behavioral modes** for optimized workflows

+#### Production Config Collections
+
+For **battle-tested, ready-to-use configurations** from production environments:
+
+| Repository | Author | Stats | Focus |
+|------------|--------|-------|-------|
+| [**everything-claude-code**](https://github.com/affaan-m/everything-claude-code) | Affaan Mustafa (Anthropic hackathon winner) | ⭐ 31.9k | Production configs from 10+ months intensive use |
+
+**Why this matters**: This is the **largest community-validated Claude Code resource** (31.9k stars in 9 days). Unlike tutorials, these are **configs proven in production** through winning Anthropic's hackathon (Zenith project).
+
+**Unique innovations not found elsewhere**:
+- **mgrep**: 50% token reduction vs standard grep/ripgrep
+- **hookify**: Conversational hook creation (describe need → JSON generated)
+- **pass@k metrics**: Formal verification approach (k=3 → 91% success rate)
+- **Sandboxed subagents**: Tool restrictions per agent (security-reviewer can't Edit files)
+- **Plugin ecosystem**: One-command installation for all configs
+
+**Positioning**: Complementary to this guide—we teach concepts ("why"), they provide production configs ("how").
+
+**See also**: [Comprehensive evaluation](../docs/resource-evaluations/015-everything-claude-code-github-repo.md) (Score 5/5)
+
+---
+
 #### SuperClaude Behavioral Modes

 > ⚠️ **Non-official Extension**: SuperClaude flags (`--learn`, `--uc`, `--think`, etc.) are **NOT Claude Code CLI flags**. They work via prompt injection in CLAUDE.md files and require installing the SuperClaude framework.
--- a/guide/workflows/task-management.md
+++ b/guide/workflows/task-management.md
@ -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