Response Awareness (RA) Methodology

This skill guides you through the Response Awareness methodology for creating and managing tasks with proper assumption tracking across all programming and development work.

Critical Requirements

⚠️ MANDATORY: CREATE A TASK BEFORE DOING ANY WORK

• •NO code changes without a task
• •NO file edits without a task
• •NO implementations without a task
• •Create task BEFORE reading code, writing code, or making changes

Quick Workflow

1. CREATE TASK FIRST → 2. Assess complexity (1-10) → 3. Set RA mode →
4. Implement with RA tags → 5. Log progress → 6. Status: REVIEW → 7. Validate → 8. DONE

Complexity Assessment (1-10 Scale)

Score based on: code size, domains affected, integration points, uncertainty level

• •1-3: Simple Mode - Direct implementation, basic testing
• •4-6: Standard Mode - Document assumptions, comprehensive testing
• •7-8: RA-Light Mode - Extensive RA tagging, verification needed
• •9-10: RA-Full Mode - Multi-agent orchestration required

For detailed scoring criteria, see COMPLEXITY_SCORING.md.

RA Modes Explained

Simple Mode (1-3)

• •Direct implementation with MANDATORY RA awareness
• •RA tags REQUIRED for ALL assumptions
• •Basic error handling and testing
• •Knowledge capture: ONLY for problems/gotchas
• •Completion: MUST go to REVIEW for assumption validation

Standard Mode (4-6)

• •Structured implementation with MANDATORY RA awareness
• •RA tags REQUIRED for ALL decisions and uncertainties
• •Document assumptions in code comments AND RA tags
• •Comprehensive error handling and testing
• •Knowledge capture: ONLY for problems/gotchas encountered
• •Completion: MUST go to REVIEW for assumption validation

RA-Light Mode (7-8)

• •Extensive RA tagging required throughout
• •Every assumption must be tagged with specific content
• •Don't implement SUGGEST_* items - just tag them
• •Comprehensive knowledge documentation
• •Flag for verification: update_task(ra_metadata={"verification_needed": True})
• •Completion: ALWAYS goes to REVIEW

RA-Full Mode (9-10)

• •DO NOT implement directly - requires orchestration
• •Deploy multiple specialized agents
• •Coordinate with atomic task locking
• •Full verification phase required
• •Comprehensive knowledge management

RA Tags - Track Your Assumptions

🚨 CRITICAL: You MUST use the add_ra_tag MCP tool to record assumptions as you implement.

Implementation Tags

• •#COMPLETION_DRIVE_IMPL: Specific implementation assumption
• •#COMPLETION_DRIVE_INTEGRATION: System integration assumption
• •#CONTEXT_DEGRADED: Fuzzy memory, making educated guess
• •#CONTEXT_RECONSTRUCT: Actively filling in missing details

Pattern Detection Tags

• •#CARGO_CULT: Code from pattern association, not requirement
• •#PATTERN_MOMENTUM: Methods/features from completion drive
• •#ASSOCIATIVE_GENERATION: Features that feel like they should exist

Conflict Tags

• •#PATTERN_CONFLICT: Multiple contradictory patterns feel valid
• •#TRAINING_CONTRADICTION: Different contexts suggest opposing approaches

Suggestion Tags

• •#SUGGEST_ERROR_HANDLING: Error handling that feels needed
• •#SUGGEST_EDGE_CASE: Edge cases should probably be handled
• •#SUGGEST_VALIDATION: Input validation seems important
• •#SUGGEST_CLEANUP: Resource cleanup feels necessary
• •#SUGGEST_DEFENSIVE: Defensive programming seems prudent

For complete tag catalog with examples, see RA_TAGS_CATALOG.md.

How to Add RA Tags

During implementation, use the MCP tool:

add_ra_tag(
    task_id="current_task_id",
    ra_tag_text="#COMPLETION_DRIVE_IMPL: Assuming database connection pooling",
    agent_id="claude"
)

⛔ DO NOT just think about assumptions ✅ DO record every assumption using the tool

Task Creation

Always create tasks first:

create_task(
    name="Implement user authentication",
    description="Add OAuth2 authentication support",
    epic_name="Authentication System",
    project_name="My Project",
    ra_mode="standard",
    ra_score="5"
)

Task Status Workflow

TODO → IN_PROGRESS → REVIEW → DONE

Status Transitions

Start work:

update_task_status(task_id, "IN_PROGRESS", agent_id)  # Auto-acquires lock

Ready for review:

update_task_status(task_id, "REVIEW", agent_id)  # Releases lock for reviewer

Mark complete:

update_task_status(task_id, "DONE", agent_id)  # Auto-releases lock

CRITICAL: If RA tags were used during implementation, task MUST go to REVIEW status, not directly to DONE. RA tags indicate assumptions that require validation.

Knowledge Capture Guidelines

Capture knowledge ONLY for:

• •✅ Trial-and-error solutions (took multiple attempts)
• •✅ Non-obvious gotchas discovered
• •✅ User corrections (what NOT to do)
• •✅ Integration challenges that required research

Do NOT capture:

• •❌ Routine implementation details
• •❌ Standard patterns
• •❌ Obvious solutions

Example:

upsert_knowledge(
    title="PostgreSQL FTS GIN Index Gotcha",
    content="Problem: Search was slow (2000ms). Tried: 1) BTREE index (no improvement), 2) Increasing work_mem (no improvement), 3) Finally discovered: FTS needs GIN index, not BTREE. Command: CREATE INDEX USING gin(to_tsvector('english', content)). Reduced search time to 50ms.",
    category="database_gotchas",
    tags='["postgresql", "fts", "gin_index", "performance"]',
    task_id="current_task_id"
)

MCP Tools Reference

Task Management

• •create_task() - Create new task with RA metadata
• •update_task() - Update task fields, RA tags, logs
• •update_task_status() - Change status with auto-locking
• •get_task_details() - Retrieve complete task info
• •add_ra_tag() - Add assumption tags during implementation

Knowledge Management

• •get_knowledge() - Retrieve knowledge items
• •upsert_knowledge() - Create/update knowledge
• •append_knowledge_log() - Track knowledge changes

Task Locking

• •acquire_task_lock() - Manual lock (multi-agent only)
• •release_task_lock() - Manual unlock
• •Preferred: Use update_task_status() for automatic lock management

Workflow Examples

See the examples directory for complete workflows:

• •Simple Mode Example
• •Standard Mode Example
• •RA-Light Mode Example

Quality Standards

ALL MODES:

• •Production-ready code with proper error handling
• •Follow project conventions and patterns
• •No TODO comments left in final code
• •All acceptance criteria met

RA MODES ADDITIONAL:

• •All assumptions explicitly tagged
• •Integration points validated
• •Pattern decisions documented
• •Ready for verification phase

Common Pitfalls

Parameter Format Errors

RA tags must be JSON string arrays:

• •✓ Correct: ra_tags='["#TAG: description"]'
• •✗ Wrong: ra_tags=["#TAG: description"]

Skipping REVIEW Status

If you used RA tags, the task MUST go through REVIEW before DONE.

Forgetting to Add Tags

Don't just think about assumptions - use add_ra_tag() to record them.

Over-capturing Knowledge

Only capture hard-won insights, not routine implementations.

Version

RA Methodology v3.0.0 - Comprehensive assumption tracking across all complexity levels