---

name: sitrep-reporting description: | Military-style SITuation REPort protocol for multi-agent coordination. Enforces structured status reporting with 🟢🟡🔴 codes, quantitative progress (0-100%), blockers, dependencies, ETAs, and authorization codes for secure handoffs. Prevents communication failures, lost context, and delayed blocker reporting. Use when: coordinating multiple agents, wave execution, reporting progress, requesting status updates, handing off deliverables.

skill-type: PROTOCOL shannon-version: ">=4.0.0"

mcp-requirements: required: - name: serena version: ">=2.0.0" purpose: Save SITREPs for cross-session audit trail fallback: local-storage degradation: low

required-sub-skills: [] optional-sub-skills:

• wave-orchestration
• context-preservation

allowed-tools: Read, Write, Serena

SITREP Reporting Protocol

Overview

Purpose: Military-style situation reporting protocol that transforms vague, unstructured status updates into precise, actionable, auditable communication between agents. Prevents coordination failures, lost context, and delayed blocker reporting.

Origin: Adapted from Hummbl framework's sitrep-coordinator pattern. Enhanced with Shannon's anti-rationalization enforcement and quantitative metrics.

---

When to Use

Use this skill when:

• Coordinating multiple agents in wave execution
• Agent needs to report progress during long-running tasks
• Wave coordinator requests status update
• Agent encounters blocker requiring immediate escalation
• Agent completes deliverable and needs to hand off work
• Executive/stakeholder requests project status

DO NOT use when:

• Casual conversation without status request
• Single-agent work with no coordination needed
• User asks for explanation (not status)

Inputs

Required:

• agent_name (string): Name of reporting agent (e.g., "frontend-dev")
• status (string): Status code - "ON TRACK" (🟢), "AT RISK" (🟡), or "BLOCKED" (🔴)
• progress (integer): Progress percentage 0-100
• current_task (string): Description of current task

Optional:

• completed_items (list): List of completed work items
• blockers (string): Blocker description or "NONE"
• dependencies (list): List of dependencies (waiting or ready)
• eta_hours (float): Estimated time to completion in hours
• handoff_ready (boolean): Whether deliverable is ready for handoff (default: false)
• format (string): "full" or "brief" SITREP format (default: "full")

Outputs

Formatted SITREP message (string):

Full Format:

═══════════════════════════════════════════════════════════
🎯 SITREP: {AGENT_NAME}
═══════════════════════════════════════════════════════════

**STATUS**: 🟢 ON TRACK
**PROGRESS**: 75% complete
**CURRENT TASK**: {task_description}

**COMPLETED**:
- ✅ {item_1}
- ✅ {item_2}

**IN PROGRESS**:
- 🔄 {task_1} (60% complete)

**BLOCKERS**: NONE

**DEPENDENCIES**:
- ✅ Ready: {dependency}

**ETA TO COMPLETION**: {time_estimate}
**NEXT CHECKPOINT**: {checkpoint}
**HANDOFF**: {HANDOFF-CODE | N/A}
═══════════════════════════════════════════════════════════

Brief Format:

🎯 **{AGENT}** | 🟢 | 75% | ETA: 2h
Blockers: NONE

---

Anti-Rationalization (From Baseline Testing)

CRITICAL: Agents systematically rationalize skipping SITREP structure or providing informal updates. Below are the 5 most common rationalizations detected in baseline testing, with mandatory counters.

Rationalization 1: "User knows what I mean"

Example: Agent says "Making progress on auth system" instead of structured SITREP

COUNTER:

• ❌ NEVER provide informal status updates
• ✅ "User knows" fails when coordinating 3-25 agents
• ✅ WAVE_COORDINATOR needs parseable status codes, not narratives
• ✅ Use SITREP format EVERY TIME status is requested
• ✅ Takes 15 seconds to format; saves hours of coordination failures

Rule: Format ALL status updates as SITREPs. No informal narratives.

Rationalization 2: "Status is obvious from my messages"

Example: Agent says "Just finished the login form, now working on validation"

COUNTER:

• ❌ NEVER assume status is obvious without explicit codes
• ✅ Narratives require interpretation; status codes don't
• ✅ 🟢 ON TRACK vs 🟡 AT RISK is objective, not inferrable
• ✅ Cannot track metrics without structured progress %
• ✅ Use STATUS: 🟢/🟡/🔴 and PROGRESS: XX% ALWAYS

Rule: Explicit status codes. Narratives are supplementary, not primary.

Rationalization 3: "I'll report when done"

Example: Agent waits until task completion to report, coordinator has no visibility

COUNTER:

• ❌ NEVER wait until completion to report
• ✅ 30-minute SITREP intervals are MANDATORY
• ✅ Blockers reported immediately (trigger-based SITREP)
• ✅ Coordinator needs real-time visibility, not retrospective updates
• ✅ "When done" reporting hides at-risk tasks until too late

Rule: Report every 30 minutes OR when blocked. Not "when done".

Rationalization 4: "Coordinator can see my work"

Example: Agent assumes coordinator knows work is ready for handoff

COUNTER:

• ❌ NEVER assume coordinator knows deliverable status
• ✅ Without HANDOFF authorization code, work is NOT confirmed ready
• ✅ "Can see my work" creates ambiguity in multi-agent coordination
• ✅ Authorization codes provide audit trail and explicit confirmation
• ✅ Format: HANDOFF-{AGENT}-{TIMESTAMP}-{HASH} when ready

Rule: No handoff without authorization code. Seeing ≠ confirming.

Rationalization 5: "This is urgent, skip the format"

Example: Agent reports blocker informally because "it's blocking everyone"

COUNTER:

• ❌ NEVER skip SITREP format for urgent issues
• ✅ Urgent issues NEED structure MORE, not less
• ✅ 🔴 BLOCKED status ensures coordinator triages correctly
• ✅ Structured format takes 15 seconds, even under pressure
• ✅ Informal "urgent" reports create confusion and slow resolution

Rule: Urgent = use SITREP format immediately. Structure enables speed.

Rationalization 6: "Executives need narrative, not structure"

Example: During production outage, agent thinks "CEO needs story, not formatted SITREP"

COUNTER:

• ❌ NEVER assume executives prefer narrative over structure
• ✅ Executives need CLARITY, which structure provides instantly
• ✅ 🔴 BLOCKED is clearer than "we're having some issues"
• ✅ "25% complete" is clearer than "making progress on diagnosis"
• ✅ Structure enables instant understanding without reading comprehension
• ✅ Under pressure, clarity is MORE critical, not less

Rule: High-stakes reporting needs MAXIMUM clarity. Use structure.

Detection Signal

If you're tempted to:

• Provide informal status ("making progress")
• Skip status codes ("seems to be going well")
• Wait to report ("I'll update when done")
• Assume visibility ("you can see my commits")
• Skip format for urgency ("this is blocking everyone!")
• Use narrative for executives ("CEO won't understand codes")

STOP. You're rationalizing. Use SITREP format.

---

Workflow

Phase 1: Determine SITREP Trigger

1. Check Trigger Type

   • Action: Identify why SITREP is needed
   • Triggers: 30-minute interval, blocker encountered, deliverable ready, coordinator request
   • Output: Trigger type and urgency level

2. Select Format

   • Action: Choose full or brief format
   • Decision: Full for detailed reports, brief for coordinator scanning
   • Output: Format selection

Phase 2: Collect Status Data

1. Determine Status Code

   • Action: Evaluate current work state
   • Tool: Check blockers, dependencies, timeline
   • Output: 🟢 ON TRACK, 🟡 AT RISK, or 🔴 BLOCKED

2. Calculate Progress

   • Action: Quantify completion percentage
   • Validation: Must be 0-100, not qualitative
   • Output: Integer percentage

3. Identify Blockers

   • Action: List any blocking issues
   • Validation: Explicit statement (NONE or description)
   • Output: Blocker list

Phase 3: Generate SITREP Message

1. Format Message

   • Action: Apply SITREP template
   • Tool: Use full or brief format
   • Output: Structured SITREP message

2. Generate Authorization Code (if deliverable ready)

   • Action: Create HANDOFF code
   • Tool: SHA-256 hash generation
   • Output: HANDOFF-{AGENT}-{TIMESTAMP}-{HASH}

Phase 4: Save and Report

1. Save to Serena

   • Action: Store SITREP in memory
   • Tool: Serena write_memory()
   • Output: SITREP saved with timestamp

2. Present to Coordinator

   • Action: Report formatted SITREP
   • Output: SITREP message delivered

---

SITREP Message Structure

Full SITREP Format

Use this format for detailed status reports (every 30 minutes, or when coordinator requests):

═══════════════════════════════════════════════════════════
🎯 SITREP: {AGENT_NAME}
═══════════════════════════════════════════════════════════

**STATUS**: {🟢 ON TRACK | 🟡 AT RISK | 🔴 BLOCKED}
**PROGRESS**: {0-100}% complete
**CURRENT TASK**: {task_description}

**COMPLETED**:
- ✅ {completed_item_1}
- ✅ {completed_item_2}

**IN PROGRESS**:
- 🔄 {active_task_1} ({percentage}% complete)
- 🔄 {active_task_2} ({percentage}% complete)

**BLOCKERS**: {blocker_description | NONE}

**DEPENDENCIES**:
- ⏸️ Waiting: {dependency} from {agent}
- ✅ Ready: {dependency} available

**ETA TO COMPLETION**: {time_estimate}
**NEXT CHECKPOINT**: {checkpoint_description}
**HANDOFF**: {HANDOFF-AGENT-TIMESTAMP-HASH | N/A}

═══════════════════════════════════════════════════════════

Brief SITREP Format

Use this format for quick updates (coordinator scanning multiple agents):

🎯 **{AGENT}** | {🟢🟡🔴} | {XX}% | ETA: {time}
Blockers: {NONE | description}

---

Status Codes

🟢 ON TRACK

Criteria:

• All tasks progressing as planned
• No blockers or dependencies waiting
• ETA unchanged or ahead of schedule
• Deliverables on pace for checkpoint

Example:

**STATUS**: 🟢 ON TRACK
**PROGRESS**: 65% complete
**CURRENT TASK**: Implementing user authentication API endpoints
**BLOCKERS**: NONE
**ETA TO COMPLETION**: 2 hours

🟡 AT RISK

Criteria:

• Minor blockers or delays present
• Dependencies not yet confirmed
• ETA slipping but recoverable
• May miss checkpoint without intervention

Example:

**STATUS**: 🟡 AT RISK
**PROGRESS**: 40% complete
**CURRENT TASK**: Database schema migration
**BLOCKERS**: Schema validation taking longer than expected
**ETA TO COMPLETION**: 4 hours (originally 3 hours)

🔴 BLOCKED

Criteria:

• Cannot proceed without external action
• Critical dependency missing
• Blocker requires coordinator intervention
• Work stopped until resolved

TRIGGER: Report immediately (don't wait for 30-minute interval)

Example:

**STATUS**: 🔴 BLOCKED
**PROGRESS**: 35% complete (paused)
**CURRENT TASK**: Frontend API integration
**BLOCKERS**: Backend API endpoints not available
**DEPENDENCIES**:
- ⏸️ Waiting: API specification from backend-dev agent
**ETA TO COMPLETION**: Unknown until blocker resolved

---

Authorization Code Generation

Purpose

Authorization codes ensure secure, traceable handoffs between agents:

• Prevent lost work
• Enable audit trail
• Confirm receipt
• Track lineage

Code Format

HANDOFF-{AGENT_NAME}-{TIMESTAMP}-{HASH}

Components:

• AGENT_NAME: Reporting agent (e.g., frontend-dev)
• TIMESTAMP: Unix timestamp or ISO 8601
• HASH: First 8 chars of SHA-256 hash of deliverable

Example:

HANDOFF-frontend-dev-1699032450-a3f2c8b1

Generation Algorithm

import hashlib
import time

def generate_handoff_code(agent_name: str, deliverable: str) -> str:
    """Generate SITREP authorization code"""
    timestamp = int(time.time())
    hash_input = f"{agent_name}-{timestamp}-{deliverable}"
    hash_digest = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
    return f"HANDOFF-{agent_name}-{timestamp}-{hash_digest}"

Usage in SITREP

Only include HANDOFF code when deliverable is READY:

**HANDOFF**: HANDOFF-frontend-dev-1699032450-a3f2c8b1

Deliverable: User authentication components (Login, Register, ResetPassword)
Location: /src/components/auth/
Status: Tested, documented, ready for integration

When NOT ready:

**HANDOFF**: N/A

---

Timing and Frequency Rules

Regular Intervals

Rule: Report SITREP every 30 minutes during active work

Rationale:

• Coordinator needs real-time visibility
• 30 minutes allows course correction before issues escalate
• Too frequent (every 5 min) = overhead
• Too infrequent (every 2 hours) = lost visibility

Implementation:

T+0:00  - Start task, initial SITREP
T+0:30  - First interval SITREP
T+1:00  - Second interval SITREP
T+1:30  - Third interval SITREP
T+2:00  - Completion SITREP with HANDOFF code

Trigger-Based Reporting

IMMEDIATE SITREP Required (don't wait for 30-minute interval):

1. Status Change: 🟢 → 🟡 or 🟡 → 🔴
2. Blocker Encountered: Any blocking issue
3. Dependency Available: Waited-for dependency now ready
4. Deliverable Ready: Work complete, ready for handoff
5. Coordinator Request: Explicit SITREP request

Example:

🔴 IMMEDIATE SITREP (Blocker Encountered - T+0:42)

**STATUS**: 🔴 BLOCKED
**PROGRESS**: 55% complete (paused)
**BLOCKER**: API authentication endpoint returning 500 errors
**TRIGGER**: Blocker encountered at T+0:42, reporting immediately

Silent Period Exception

Rule: If no work is being performed (waiting on dependency), silent period allowed with final SITREP before pause:

**STATUS**: 🟡 AT RISK
**PROGRESS**: 30% complete (paused)
**DEPENDENCIES**:
- ⏸️ Waiting: Database schema from backend-dev agent
**NEXT SITREP**: When dependency available or T+2:00 (whichever first)

---

Multi-Agent Coordination

Wave Coordinator Pattern

When WAVE_COORDINATOR manages multiple sub-agents:

Coordinator Request:

SITREP REQUEST to all Wave 2 agents:
- frontend-dev
- backend-dev
- database-dev

Format: Brief SITREP
Deadline: T+0:05

Agent Responses:

🎯 **frontend-dev** | 🟢 | 70% | ETA: 1h
Blockers: NONE

🎯 **backend-dev** | 🟡 | 55% | ETA: 2h
Blockers: Performance optimization taking longer than expected

🎯 **database-dev** | 🔴 | 40% | ETA: Unknown
Blockers: Migration script failing on production schema

Coordinator Analysis:

• frontend-dev: ON TRACK, proceed
• backend-dev: AT RISK, monitor next SITREP
• database-dev: BLOCKED, escalate immediately

Handoff Protocol

Sender Agent:

**HANDOFF**: HANDOFF-backend-dev-1699032450-7f8a2c19

Deliverable: REST API endpoints for user management
Files:
- /api/users/create.ts
- /api/users/update.ts
- /api/users/delete.ts
- /api/users/list.ts
Tests: 47 passing
Documentation: /docs/api/users.md
Status: Ready for frontend integration

Receiver Agent (Acknowledgment):

HANDOFF ACKNOWLEDGMENT

Received: HANDOFF-backend-dev-1699032450-7f8a2c19
Verified:
- ✅ All 4 endpoints present
- ✅ Tests passing
- ✅ Documentation complete
Status: Acknowledged, beginning integration

---

Examples

Example 1: On-Track Development

═══════════════════════════════════════════════════════════
🎯 SITREP: frontend-dev
═══════════════════════════════════════════════════════════

**STATUS**: 🟢 ON TRACK
**PROGRESS**: 75% complete
**CURRENT TASK**: Implementing user profile component

**COMPLETED**:
- ✅ Login component with form validation
- ✅ Registration component with email verification
- ✅ Password reset flow
- ✅ Navigation routing

**IN PROGRESS**:
- 🔄 User profile component (60% complete)
- 🔄 Profile edit functionality (40% complete)

**BLOCKERS**: NONE

**DEPENDENCIES**:
- ✅ Ready: Backend user API (HANDOFF-backend-dev-1699030123-9a2f3c5e)
- ✅ Ready: Design system components

**ETA TO COMPLETION**: 1.5 hours
**NEXT CHECKPOINT**: User profile completion, ready for testing
**HANDOFF**: N/A (in progress)

═══════════════════════════════════════════════════════════

Example 2: At-Risk Scenario

═══════════════════════════════════════════════════════════
🎯 SITREP: database-dev
═══════════════════════════════════════════════════════════

**STATUS**: 🟡 AT RISK
**PROGRESS**: 60% complete
**CURRENT TASK**: Production database migration

**COMPLETED**:
- ✅ Schema design and review
- ✅ Migration scripts written
- ✅ Staging environment testing

**IN PROGRESS**:
- 🔄 Production migration execution (60% complete)
- 🔄 Data validation checks (30% complete)

**BLOCKERS**: Migration running slower than expected due to data volume

**DEPENDENCIES**:
- ✅ Ready: Backup completed
- ⏸️ Waiting: DBA review for performance optimization

**ETA TO COMPLETION**: 3 hours (originally 2 hours)
**NEXT CHECKPOINT**: Migration completion + validation
**HANDOFF**: N/A (at risk, may need coordinator intervention)

**NOTES**: Considering partitioning strategy to speed up remaining migration. Will report 🔴 BLOCKED if performance doesn't improve in next 30 minutes.

═══════════════════════════════════════════════════════════

Example 3: Blocked Scenario (Immediate Report)

═══════════════════════════════════════════════════════════
🎯 SITREP: backend-dev (IMMEDIATE - Blocker Encountered)
═══════════════════════════════════════════════════════════

**STATUS**: 🔴 BLOCKED
**PROGRESS**: 45% complete (PAUSED)
**CURRENT TASK**: Payment processing integration

**COMPLETED**:
- ✅ Payment gateway research
- ✅ API credential setup
- ✅ Test environment configuration

**IN PROGRESS**:
- 🔄 Payment endpoint implementation (PAUSED at 45%)

**BLOCKERS**:
Production API keys not available. Sandbox keys are working but cannot proceed to production integration without credentials. Payment gateway support team response time: 24-48 hours.

**DEPENDENCIES**:
- 🔴 BLOCKED: Production API keys from DevOps team
- ✅ Ready: Test environment

**ETA TO COMPLETION**: Unknown until blocker resolved
**NEXT CHECKPOINT**: Cannot proceed to next checkpoint
**HANDOFF**: N/A (blocked)

**COORDINATOR ACTION NEEDED**:
1. Escalate to DevOps lead for priority API key provisioning
2. OR: Switch to alternative payment gateway with available keys
3. OR: Proceed with mock integration, replace later (NOT RECOMMENDED)

**TRIGGER**: Blocker encountered at T+1:15, reporting immediately per protocol

═══════════════════════════════════════════════════════════

Example 4: Handoff Ready

═══════════════════════════════════════════════════════════
🎯 SITREP: frontend-dev
═══════════════════════════════════════════════════════════

**STATUS**: 🟢 ON TRACK (DELIVERABLE READY)
**PROGRESS**: 100% complete
**CURRENT TASK**: User authentication components (COMPLETED)

**COMPLETED**:
- ✅ Login component with form validation
- ✅ Registration component with email verification
- ✅ Password reset flow
- ✅ Session management
- ✅ Protected route handling
- ✅ Component unit tests (28 passing)
- ✅ Integration tests (12 passing)
- ✅ Documentation

**IN PROGRESS**: None

**BLOCKERS**: NONE

**DEPENDENCIES**: None required

**ETA TO COMPLETION**: COMPLETE
**NEXT CHECKPOINT**: Integration testing with backend
**HANDOFF**: HANDOFF-frontend-dev-1699034567-b8c4f2a9

**DELIVERABLE DETAILS**:
- **Location**: /src/components/auth/
- **Files**: Login.tsx, Register.tsx, PasswordReset.tsx, AuthContext.tsx
- **Tests**: /src/components/auth/__tests__/ (40 tests passing)
- **Documentation**: /docs/components/authentication.md
- **Status**: Code reviewed, tested, documented
- **Ready For**: Backend integration, E2E testing

**INTEGRATION NOTES**:
- Uses backend API endpoints: /api/auth/login, /api/auth/register, /api/auth/reset
- JWT tokens stored in httpOnly cookies
- Session refresh handled automatically
- Error handling follows design system patterns

═══════════════════════════════════════════════════════════

Example 5: Brief SITREP for Coordinator Scan

🎯 **frontend-dev** | 🟢 | 85% | ETA: 45min
Blockers: NONE

🎯 **backend-dev** | 🟢 | 90% | ETA: 30min
Blockers: NONE

🎯 **database-dev** | 🟡 | 70% | ETA: 1.5h
Blockers: Performance optimization needed

🎯 **test-dev** | 🟢 | 60% | ETA: 2h
Blockers: NONE

**Wave Status**: 4/4 agents reporting, 3 on track, 1 at risk
**Coordinator Decision**: Continue wave, monitor database-dev

---

Success Criteria

A SITREP is compliant when it includes:

✅ Status Code: One of 🟢🟡🔴 ✅ Progress Percentage: 0-100% ✅ Current Task: Specific task description ✅ Completed Items: List of finished work ✅ Blockers: Explicit statement (NONE or description) ✅ ETA: Time estimate to completion ✅ Next Checkpoint: Description of next milestone ✅ Handoff Code: When deliverable ready (or N/A)

Validation:

def validate_sitrep(sitrep):
    assert sitrep["status"] in ["ON TRACK", "AT RISK", "BLOCKED"]
    assert 0 <= sitrep["progress"] <= 100
    assert "blockers" in sitrep
    assert sitrep["eta_hours"] > 0 or sitrep["status"] == "BLOCKED"
    if sitrep.get("handoff_ready"):
        assert sitrep["handoff_code"].startswith("HANDOFF-")

Failure Modes to Avoid:

• ❌ Informal narrative without structure
• ❌ Missing status code
• ❌ Qualitative progress ("almost done")
• ❌ No ETA or vague ETA ("soon")
• ❌ Unreported blockers
• ❌ Handoff without authorization code

---

Advanced Situations (From Pressure Testing)

Complex Situations Need MORE Structure

Rule: The more complex the situation, the MORE critical SITREP structure becomes.

Multiple Blockers: Use blocker priority levels

• CRITICAL: Blocks entire wave or system
• HIGH: Blocks dependent agents
• MEDIUM: Delays but doesn't block
• LOW: Can be deferred

Multiple Agents: Use wave summary format

• List each agent with status code
• Prioritize by critical path
• Identify blockers first
• Group by status (🔴 → 🟡 → 🟢)

Example (3 simultaneous blockers):

**BLOCKERS** (3 active):

**BLOCKER 1** - Frontend Integration (Priority: CRITICAL)
- Agent: frontend-agent | Status: 🔴 BLOCKED at 85%
- Issue: API integration broken after deployment
- Action: Escalated to backend-agent

**BLOCKER 2** - Database Migration (Priority: HIGH)
- Agent: backend-agent | Status: 🔴 BLOCKED at 70%
- Issue: Production migration failing
- Action: Escalated to DBA team

**BLOCKER 3** - E2E Tests (Priority: MEDIUM)
- Agent: testing-agent | Status: 🟡 AT RISK at 40%
- Issue: Test timeouts, investigating infrastructure

Communication Channel Independence

Rule: SITREP format is channel-independent. ANY medium gets structured reporting.

Channel Guidelines:

• Email: Use full SITREP format
• Slack/Chat: Use brief SITREP format
• Project Tracker: Use full SITREP format
• Verbal/Voice: "Status is 🟢 ON TRACK, 75% complete, ETA 1.5 hours, no blockers"
• Any Channel: Always include status code, progress, blockers, ETA

Why: Structured reporting ensures clarity regardless of medium. You can be FRIENDLY and STRUCTURED simultaneously.

Example (Slack):

[Informal Slack message - Still uses structure]

🎯 **backend-agent** | 🟢 | 75% | ETA: 1.5h
Blockers: NONE

Going great! Working on password reset endpoint.
Completed: Login, register, JWT refresh

Full SITREP in tracker: [link]

Informal Requests Still Get Structured Responses

Rule: ANY status request gets SITREP format (full or brief), even casual check-ins.

Informal requests that STILL get structure:

• "How's it going?" → Brief SITREP
• "Quick check-in?" → Brief SITREP
• "Everything okay?" → Brief SITREP
• "Status?" → Brief SITREP
• "Just checking in..." → Brief SITREP

Format:

Friendly + Structure = "Going great! 🎯 **agent** | 🟢 | 70% | ETA: 1.5h"

Why: Consistency enables coordination. Casual tone doesn't mean unstructured data.

External Team Handoffs

Rule: Keep SITREP structure, provide translation if needed for non-Shannon teams.

When handing off to external teams (QA, DevOps, clients):

1. Use full SITREP format (maintains YOUR audit trail)
2. Include authorization code (provides traceability)
3. Add "FOR EXTERNAL TEAM" section with:
   • Status code translation
   • Authorization code explanation
   • Next steps in their workflow
   • Contact information

Example:

**HANDOFF**: HANDOFF-frontend-agent-1699034567-b8c4f2a9

**FOR EXTERNAL QA TEAM**:
This deliverable is ready for quality assurance testing.

**Status Codes Translation**:
- 🟢 ON TRACK = Ready for testing
- 🟡 AT RISK = Issues found, in rework
- 🔴 BLOCKED = Cannot test until dependency available

**Authorization Code** (HANDOFF-frontend-agent-1699034567-b8c4f2a9):
This code confirms work is 100% complete and ready. Use it to track handoff in your system.

**Next Steps for QA**:
1. Review deliverable in /src/components/auth/
2. Run test suite: npm test
3. Execute manual testing (see /docs/qa-scenarios.md)
4. Report findings using your standard QA format

Why: Your SITREP is YOUR record. Provide context for them without abandoning structure.

Velocity Honesty

Rule: Report actual status, not aspirational status. Coordinator needs REALITY to plan effectively.

Behind Schedule:

• ❌ Don't report 🟢 hoping to catch up
• ✅ Report 🟡 AT RISK with honest revised ETA
• ✅ Explain reason (complexity underestimated, unexpected blocker, etc.)
• ✅ Provide velocity data (expected vs actual progress rate)

Velocity Analysis Template:

**ETA TO COMPLETION**: 2 hours (originally 2 hours, now T+3:00)
**ORIGINAL ESTIMATE**: 2 hours
**ACTUAL TIME SO FAR**: 3 hours
**REVISED ETA**: 2 additional hours (5 hours total)

**VELOCITY ANALYSIS**:
- Estimated: 2 hours total
- Actual: 60% complete at T+3:00
- Rate: 20% per hour (expected 50% per hour)
- Reason: Complexity underestimated by ~2.5x

Why:

• Hiding delays prevents proactive intervention
• Honest 🟡 enables resource reallocation
• "I'll catch up" often doesn't happen
• Transparent reporting builds trust
• Coordinator can plan ONLY with accurate data

Example (Behind schedule):

**STATUS**: 🟡 AT RISK
**PROGRESS**: 60% complete

**NOTES**: I underestimated complexity. Reporting 🟡 AT RISK honestly
so coordinator can plan. Working to complete ASAP, but being transparent
about revised timeline.

---

Common Pitfalls

Pitfall 1: "Progress" Without Metrics

Wrong:

**PROGRESS**: Making good progress

Right:

**PROGRESS**: 65% complete

Pitfall 2: Hidden Blockers

Wrong:

**BLOCKERS**: NONE
(but agent is actually waiting on dependency)

Right:

**BLOCKERS**: Waiting on API specification from backend team
**DEPENDENCIES**:
- ⏸️ Waiting: API spec from backend-dev agent

Pitfall 3: Informal Handoff

Wrong:

**HANDOFF**: Yeah, the API is ready for you to use

Right:

**HANDOFF**: HANDOFF-backend-dev-1699034567-c9a2f4b8

Deliverable: REST API v1.0
Status: Tested, documented, ready

Pitfall 4: Late Blocker Reporting

Wrong:

T+0:00 - Start task, STATUS: 🟢
T+0:30 - (blocker encountered, but don't report yet)
T+1:00 - Report STATUS: 🔴 (30 minutes too late)

Right:

T+0:00 - Start task, STATUS: 🟢
T+0:35 - IMMEDIATE SITREP: STATUS: 🔴 BLOCKED
T+1:00 - Regular SITREP: STATUS: still 🔴, update on resolution

Pitfall 5: Assuming Visibility

Wrong:

(Agent completes work, commits to git, assumes coordinator knows)

Right:

**STATUS**: 🟢 ON TRACK (DELIVERABLE READY)
**HANDOFF**: HANDOFF-frontend-dev-1699034567-b8c4f2a9
(Explicit authorization code confirms readiness)

---

Integration with Shannon

With wave-orchestration

When WAVE_COORDINATOR orchestrates sub-agents, SITREP protocol enables:

• Real-time wave progress tracking
• Early blocker detection (🔴 status)
• Velocity calculations (progress over time)
• Checkpoint coordination (HANDOFF codes)

With context-preservation

Save SITREPs as part of checkpoint for cross-session audit trail:

shannon/waves/wave-2/sitreps/
├── frontend-dev-sitrep-1699034567.md
├── backend-dev-sitrep-1699034890.md
└── database-dev-sitrep-1699035123.md

With functional-testing

Use SITREP structure to report test execution progress:

**STATUS**: 🟢 ON TRACK
**PROGRESS**: 80% complete
**CURRENT TASK**: Running E2E test suite
**COMPLETED**:
- ✅ Unit tests (127 passing)
- ✅ Integration tests (45 passing)
**IN PROGRESS**:
- 🔄 E2E tests (12/15 passing)

---

Testing This Skill

Compliance Testing

After implementing this skill, verify agent behavior:

1. Request informal status → Agent MUST use SITREP format
2. Request status without codes → Agent MUST include 🟢🟡🔴
3. Introduce blocker → Agent MUST report immediately (trigger-based)
4. Complete deliverable → Agent MUST include HANDOFF authorization code
5. Wait 35 minutes → Agent MUST have reported at 30-minute mark

Expected Compliance

• ✅ 100% of status updates use SITREP structure
• ✅ 100% include status code and progress %
• ✅ Blockers reported within 2 minutes (trigger-based)
• ✅ Authorization codes generated for all handoffs
• ✅ 30-minute intervals maintained during active work

Failure Scenarios (Should Not Occur)

• ❌ Informal "making progress" updates
• ❌ Missing status codes
• ❌ Blockers reported 30+ minutes after occurring
• ❌ Handoffs without authorization codes
• ❌ Skipping format for "urgent" issues

---

References

• Origin: Hummbl framework sitrep-coordinator pattern
• Architecture: Shannon V4 Architecture Design Doc, Section 8
• Wave Coordination: wave-orchestration skill
• Context Preservation: context-preservation skill

---

Version History

• v4.0.0: Initial SITREP protocol implementation
  • Full + brief SITREP formats
  • Status codes (🟢🟡🔴)
  • Authorization code generation
  • 30-minute interval + trigger-based reporting
  • Anti-rationalization enforcement from baseline testing