docs: tea editorial review

[muratkeremozcan]

Summary

Condense the TEA overview for faster scanning, clarify phase placement, and tighten optional integration guidance.

Changes

• Reordered content: command catalog moved up; phase numbering note placed before the lifecycle diagram.
• Simplified “Why TEA is Different” to a tighter multi‑phase summary plus the workflow table.
• Condensed track cheat sheets to tables with brief key notes; removed long execution notes and worked examples.
• Merged Playwright Utils + MCP content into a single “Optional Integrations” section.
• Clarified Playwright Utils enable/disable as an installer‑managed choice with an override note.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation update to TEA overview file reorganizing and condensing existing content. Added TEA Command Catalog, Workflow Lifecycle phases with Mermaid diagram, Track Cheat Sheets, and Enterprise Deltas sections. Updated terminology and MCP enhancement descriptions for clarity.

Changes

Cohort / File(s)

Summary

TEA Overview Documentation docs/explanation/features/tea-overview.md

Added TEA Command Catalog table with command details and MCP enhancements. Introduced Workflow Lifecycle section with phase-based structure and Phase 2–Gate Mermaid diagram. Condensed and reorganized multiple sections to unify terminology (e.g., "TEA Is Different" → "Why TEA Is Different"). Replaced verbose execution notes with concise bullet points. Added Track Cheat Sheets (Condensed) and Enterprise Deltas from BMad Method sections. Updated Playwright MCP Enhancements content and added Related how-to guides section. Net: consolidated 151 lines through restructuring.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• docs: add TEA design philosophy callout and context engineering glossary entry #1303: Adds complementary conceptual content (design/philosophy callout and context engineering glossary entry) to the same TEA overview documentation file alongside this PR's workflow and catalog additions.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'docs: tea editorial review' is directly related to the changeset, which consists entirely of editorial improvements to the tea-overview.md documentation file.
Description check	✅ Passed	The PR description clearly explains the editorial changes made to the TEA overview documentation, including condensing content, reordering sections, simplifying explanations, and merging related content.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/tea-editorial-review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/explanation/features/tea-overview.md (1)

207-216: Critical inconsistency: System-level *test-design missing from Phase 3 in all cheat sheets.

The Workflow Lifecycle section (lines 71, 156-159, 163) and the Mermaid diagram (line 91) clearly establish that system-level *test-design runs in Phase 3 after architecture. However, all three Track Cheat Sheets omit this command from their Phase 3 rows:

• Greenfield BMad Method (line 211): Shows only *framework, *ci
• Brownfield (line 240): Shows only *framework, *ci
• Greenfield Enterprise (line 268): Shows only *framework, *ci

Users following the cheat sheets will miss the critical system-level test design step, potentially impacting ADR testability review and the implementation-readiness gate.

📋 Proposed fix: Add system-level test-design to Phase 3 rows

For Greenfield BMad Method (around line 211):

-| **Phase 3**: Solutioning   | Run `*framework`, `*ci` AFTER architecture and epic creation      | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test scaffold, CI pipeline    |
+| **Phase 3**: Solutioning   | Run `*test-design` (system-level) after architecture, then `*framework`, `*ci` AFTER epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | `test-design-system.md`, architecture, epics/stories, test scaffold, CI pipeline |

Apply similar changes to the Brownfield (line 240) and Greenfield Enterprise (line 268) tables.

Also applies to: 235-245, 264-272

🧹 Nitpick comments (2)

docs/explanation/features/tea-overview.md (2)

169-177: Summary table omits system-level *test-design from Phase 3.

While this is a high-level summary table (not a step-by-step guide), line 174 shows Phase 3 with only *framework, *ci, omitting system-level *test-design that's described in the Workflow Lifecycle section. Consider adding it for completeness:

| **Phase 3** | \*test-design (system-level), \*framework, \*ci | Once per project | System testability review and test infrastructure setup |

---

26-29: Consider clarifying framework/ci dependencies for standalone use.

Line 29 states "Run *framework or *ci only if you want TEA to scaffold the harness or pipeline" but doesn't clarify that these typically benefit from architectural context (even in standalone mode). Consider adding a brief note about when to run these in the standalone sequence.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d419ac8 and fb84862.

📒 Files selected for processing (1)

• docs/explanation/features/tea-overview.md

🧰 Additional context used

📓 Path-based instructions (1)

**/*

⚙️ CodeRabbit configuration file

**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:

<code changes>

Files:

• docs/explanation/features/tea-overview.md