Refactor code structure for improved readability and maintainability

.github/agents/speckit.analyze.agent.md

@@ -59,6 +59,8 @@ Load only the minimal necessary context from each artifact:
 - Phase grouping
 - Parallel markers [P]
 - Referenced file paths
+- Context blocks (per-task): code signatures, implementation patterns, gotchas, acceptance signals
+- Phase Context summaries: files modified, key types/interfaces, codebase conventions
 
 **From constitution:**
 
@@ -111,14 +113,26 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
 - Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
 
+#### G. Implementation Self-Containment
+
+**Why this matters**: Tasks will be executed by a less-capable implementing model (e.g., Sonnet) that cannot reliably infer implementation details from sparse descriptions. Every non-trivial task must be a standalone implementation brief.
+
+- **Missing Context blocks**: Flag any non-trivial task (anything beyond adding a simple field or creating an empty file) that lacks an indented **Context** block beneath the checkbox line. Severity: HIGH.
+- **Missing code signatures**: Context blocks that describe interfaces, structs, or functions the task depends on but do NOT quote the actual signatures with fenced code blocks. Severity: HIGH.
+- **Missing implementation pattern**: Context blocks that say *what* to build but not *how* — no code skeleton, no pseudocode, no reference to an analogous pattern elsewhere in the codebase. Severity: MEDIUM.
+- **Missing acceptance signal**: Tasks without a concrete, verifiable "done" statement (e.g., a specific test command, a build command, or observable output). Severity: MEDIUM.
+- **Missing gotchas/constraints**: Tasks that touch complex logic (edge cases, platform constraints, performance-sensitive code) but whose Context block omits known pitfalls from the spec or research documents. Severity: MEDIUM.
+- **Missing Phase Context summary**: Phases that lack the opening block listing files modified, key types, and codebase conventions. Severity: LOW.
+- **Placeholder signatures**: Context blocks that contain generic or assumed code signatures not verified against the actual codebase (e.g., `func DoSomething()` when the real signature has different parameters). Severity: HIGH.
+
 ### 5. Severity Assignment
 
 Use this heuristic to prioritize findings:
 
 - **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
-- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
-- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
-- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion, non-trivial task missing Context block or code signatures (blocks implementation by less-capable model)
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case, Context block missing implementation pattern or acceptance signal
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order, missing Phase Context summary
 
 ### 6. Produce Compact Analysis Report
 
@@ -145,9 +159,12 @@ Output a Markdown report (no file writes) with the following structure:
 
 - Total Requirements
 - Total Tasks
+- Non-Trivial Tasks (tasks requiring Context blocks)
 - Coverage % (requirements with >=1 task)
+- Context Completeness % (non-trivial tasks with a complete Context block containing: code signatures, implementation pattern, and acceptance signal)
 - Ambiguity Count
 - Duplication Count
+- Self-Containment Issues Count (from Detection Pass G)
 - Critical Issues Count
 
 ### 7. Provide Next Actions