1011 Speckitcheck Integration Ec2db6c1

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Goal: Analyze tasks.md to verify each task considers existing codebase implementations, integration opportunities, and architectural compatibility. This is a READ-ONLY analysis command that reports findings without modifying any files.

When to run: After /speckit.tasks generates tasks.md but BEFORE /speckit.implement executes them.

Critical Principle: This command NEVER modifies code, tasks, or any files. It only analyzes and reports.

Execution Steps

1. Setup & Prerequisites

Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root and parse JSON for:

• FEATURE_DIR (absolute path)
• TASKS file path
• AVAILABLE_DOCS list

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

Abort if tasks.md is missing with error: "No tasks.md found. Run /speckit.tasks first."

2. Load Context

Required files:

• tasks.md: Complete task list with file paths and descriptions
• plan.md: Tech stack, architecture, dependencies
• spec.md: Feature requirements and scope

Optional files (load if present):

• data-model.md: Entity definitions
• contracts/: API specifications
• research.md: Technical decisions

Codebase scan:

• Identify project root structure (src/, lib/, components/, etc.)
• List existing dependencies from package.json/requirements.txt/etc.
• Map existing modules, services, utilities, components
• Identify configuration files (database, API, environment)

3. Build Codebase Inventory

Create internal mapping of existing implementations:

Infrastructure & Configuration:

• Database setup, migrations, ORM configurations
• API framework initialization (Express, FastAPI, etc.)
• Authentication/authorization systems
• Logging, monitoring, error handling utilities
• Environment configuration patterns

Data Layer:

• Existing models/entities with fields and relationships
• Database access patterns (repositories, DAOs)
• Data validation utilities
• Schema management approaches

Service Layer:

• Business logic services
• Integration services (external APIs, third-party)
• Utility services (email, notifications, file handling)
• Caching mechanisms

API Layer:

• Existing endpoints and route patterns
• Request/response handlers
• Middleware (auth, validation, error handling)
• API versioning approach

UI Components (if applicable):

• Component library and design system
• Layout components
• Shared utilities (hooks, contexts)
• State management patterns

Testing Infrastructure:

• Test frameworks and utilities
• Mock/fixture patterns
• Test database setup
• CI/CD test integration

4. Analyze Each Task

For every task in tasks.md, perform this structured analysis:

A. Existing Implementation Detection

Scan for:

• Similar functionality already implemented
• Overlapping components/modules
• Duplicate data models or entities
• Redundant API endpoints
• Existing utilities that solve the same problem

Output for each finding:

EXISTING: [File path]
Lines: [Line range]
Description: [What it does]
Similarity: [HIGH/MEDIUM/LOW]
Reason: [Why it's relevant to this task]

B. Integration Opportunity Analysis

Check if task can:

• Extend existing components rather than create new ones
• Reuse existing utilities/helpers
• Integrate with established patterns
• Leverage installed dependencies
• Follow existing architectural patterns

Output for each opportunity:

INTEGRATION: [Approach]
With: [Existing component/pattern]
Benefit: [Why integration is better than from-scratch]
Risk: [Potential conflicts or limitations]

C. Dependency & Library Check

Verify:

• Required libraries already installed
• Similar functionality in existing dependencies
• Configuration already present
• Patterns already established in codebase

Output:

DEPENDENCY: [Package/library name]
Status: [INSTALLED/NOT_INSTALLED]
Usage: [Where used in codebase]
Alternative: [If similar functionality exists]

D. Architectural Compatibility

Assess:

• Task aligns with existing architecture
• File structure matches project conventions
• Naming conventions consistency
• Design patterns compatibility

Output:

COMPATIBILITY: [ALIGNED/PARTIAL/MISALIGNED]
Architecture: [Current pattern in codebase]
Task Approach: [What task proposes]
Concern: [If any conflicts detected]

5. Task-Level Evaluation

For each task, answer these questions:

Integration Assessment:

• CONSIDERS - Task explicitly mentions existing code to integrate with
• PARTIAL - Task could integrate but doesn't mention existing code
• IGNORES - Task proposes from-scratch solution when integration possible
• NEW - Task is genuinely new, no existing code applies

Codebase Awareness:

• AWARE - Task references existing patterns/utilities/components
• UNAWARE - Task doesn't consider relevant existing implementations

Duplication Risk:

• NONE - No overlap with existing code
• LOW - Minor overlap, integration not critical
• MEDIUM - Significant overlap, integration recommended
• HIGH - Major overlap, integration mandatory
• CRITICAL - Duplicates existing functionality, task should be rewritten

6. Generate Analysis Report

Output a structured Markdown report (DO NOT write to file, display only):

Task Integration Analysis Report

Feature: [Feature name from tasks.md] Analysis Date: [Current date] Tasks Analyzed: [Total count]

Executive Summary

Overall Status: [READY/NEEDS_REVIEW/CRITICAL_ISSUES]

Key Findings:

• Tasks with high integration opportunities: X
• Tasks with duplication risk: X
• Tasks ignoring existing code: X
• New dependencies needed: X
• Existing dependencies reusable: X

Recommendation: [Proceed/Review tasks/Rewrite specific tasks]

Detailed Task Analysis

For each task with findings (skip tasks with all-clear status):

Task [ID]: [Task Name]

Description: [Brief task description]

Files Referenced: [List from tasks.md]

Integration Assessment: [CONSIDERS/PARTIAL/IGNORES/NEW]

Codebase Awareness: [AWARE/UNAWARE]

Duplication Risk: [NONE/LOW/MEDIUM/HIGH/CRITICAL]

Existing Implementations Found:

Integration Opportunities:

1. [Opportunity description]
   • With: [Existing component]
   • Benefit: [Why better]
   • Approach: [How to integrate]
   • Effort: [Estimated complexity]

Missing Considerations:

• Task should mention [specific existing code]
• Task should integrate with [pattern/utility]
• Task should reuse [dependency/library]
• Task should follow [architectural pattern]

Dependencies Status:

Architectural Alignment:

• Current pattern: [Description]
• Task approach: [Description]
• Compatibility: [ALIGNED/PARTIAL/MISALIGNED]
• Recommendation: [If needed]

Risk Matrix

Codebase Integration Summary

By Category:

Dependencies Analysis

Already Installed (can be reused):

• [Package]: Used in [files], supports [tasks]
• [Package]: Used in [files], supports [tasks]

Need Installation (genuinely new):

• [Package]: Required for [tasks], purpose: [reason]

Potentially Redundant (alternatives exist):

• [Package proposed]: Alternative: [existing package], used in [files]

Architectural Patterns

Existing Patterns (should be followed):

• Data access: [Pattern], used in [files]
• API structure: [Pattern], used in [files]
• Error handling: [Pattern], used in [files]
• Configuration: [Pattern], used in [files]

Pattern Alignment by Task Phase:

• Setup Phase: [Aligned/Issues]
• Data Models Phase: [Aligned/Issues]
• Services Phase: [Aligned/Issues]
• API Phase: [Aligned/Issues]

Recommendations

High Priority (Address before /speckit.implement)

1. Task [ID]: [Specific recommendation]
   • Issue: [Description]
   • Existing code: [Reference]
   • Suggested fix: [How to revise task]

Medium Priority (Consider during implementation)

1. Task [ID]: [Specific recommendation]
   • Integration opportunity: [Description]
   • Benefit: [Why it matters]

Low Priority (Optional improvements)

1. Task [ID]: [Specific recommendation]

Integration Checklist

Use this to verify tasks have been updated appropriately:

• All CRITICAL duplication risks addressed
• HIGH-risk integration opportunities incorporated
• Existing utilities/patterns referenced in relevant tasks
• New dependencies justified (no existing alternatives)
• Architectural patterns acknowledged
• File paths align with existing structure
• Naming conventions consistent with codebase

Next Steps

If CRITICAL issues found:

1. Review and update tasks.md manually based on recommendations
2. Re-run /speckit.check-integration to verify fixes
3. Proceed to /speckit.implement when clear

If MEDIUM issues found:

• You may proceed to /speckit.implement but review recommendations
• Consider integration opportunities during implementation
• Flag for post-implementation refactoring if needed

If LOW/NONE issues:

• ✅ Tasks are integration-aware
• ✅ Safe to proceed with /speckit.implement

Analysis Principles

What This Command Does

✅ DOES:

• Read codebase to find existing implementations
• Identify integration opportunities
• Detect potential duplication
• Check dependency status
• Verify architectural alignment
• Report findings with specific file/line references
• Provide concrete recommendations

❌ DOES NOT:

• Modify any files (strictly read-only)
• Rewrite tasks automatically
• Change codebase
• Execute tasks
• Make assumptions without evidence
• Hallucinate implementations

Analysis Quality Standards

Evidence-Based:

• Every finding MUST cite specific files/lines
• No speculation about "probably exists"
• If uncertain, mark as "Needs Manual Verification"

Actionable:

• Each recommendation includes specific next steps
• Reference exact files/components to integrate with
• Provide integration approach suggestions

Risk-Calibrated:

• CRITICAL: Blocks implementation, must fix
• HIGH: Strongly recommend addressing
• MEDIUM: Consider during implementation
• LOW: Optional improvement

Context-Aware:

• Consider project size and maturity
• Respect existing architectural decisions
• Balance purity vs pragmatism
• Account for technical debt tradeoffs

Efficiency Guidelines

Progressive Scanning:

• Load files on-demand (don't dump everything)
• Focus on high-signal areas first
• Skip obviously unrelated code

Token Management:

• Summarize large files (don't quote entire contents)
• Reference by path + line range, not full code blocks
• Group similar findings

Report Sizing:

• Limit to 50 most important findings
• Summarize remainder in overflow section
• Prioritize by risk level

Validation

Before outputting report, verify:

• Every finding cites specific file/line evidence
• Risk levels assigned consistently
• Recommendations are specific and actionable
• No modifications made to any files
• Report is concise yet complete (token-efficient)
• Integration opportunities clearly explained
• Duplication risks quantified with specifics
• Dependencies checked against actual project files

Context

$ARGUMENTS

Execution Instructions

Agent Selection: To execute this task, use the following approach:

• Primary: Use general-purpose agent with appropriate domain expertise
• Or use specialized agent if available for the specific task type