Team Index Reconciliation

Diagnose and fix team/roster issues for the 28-Day Metabolic Reset platform:

User Input: $ARGUMENTS

Task

1. Find the affected user or facilitator specified above
2. Diagnose team vs recruits index discrepancies (dry-run first)
3. Apply fix if canFix: true
4. Verify the user now appears in the roster

CRITICAL: Input Handling

You MUST investigate the user/team specified in the invocation above — NOT any example names in this documentation.

⛔ MANDATORY GUARDRAILS — STOP-GATES THAT CANNOT BE SKIPPED

GATE 1: Ghost User Detection

ALWAYS search BOTH DO and D1 before any team fix:

1. GET /api/debug/find-user?name={query}           → DO index
2. GET /api/admin/user-directory/search?q={query}   → D1 (catches ghosts)
3. If IDs differ → D1 ID IS CORRECT. Do NOT reconcile with ghost ID.

GATE 2: Context Recovery

Before starting, check for prior triage: SELECT id, status, admin_notes FROM bug_reports WHERE user_id = '{userId}'

GATE 3: API Retry

If any API returns 500: wait 5s → retry → wait 15s → retry. Never conclude from 1 failure.

GATE 4: SMS After Fix (MANDATORY)

After EVERY team reconciliation fix, SMS the user AND optionally the facilitator via Google Voice. CANNOT mark bug resolved until SMS is sent.

GATE 5: Blast Radius

After fixing one user's team, check: does the same facilitator have more missing members? Run POST /api/admin/reconcile-team-indexes {"groupLeaderId":"...", "fix": false} on the facilitator to find ALL discrepancies, not just the reported one.

Best Practices & Current Knowledge

MANDATORY: Always research and apply current best practices for the current month and year. Check the current date from your context (CLAUDE.md, MEMORY.md, or system prompts).

1. Check bug triage first: Before starting, read .claude/bug-triage/known-bugs.md to check if this team/roster issue has been previously reported (see BUG-001 and related entries).
2. Pattern matching: Check .claude/bug-triage/patterns.md — Pattern 2 (Index Desync) is the most common root cause for team/roster issues.
3. Use WebSearch: For unfamiliar error patterns not covered in this skill, search for current Cloudflare Workers / Durable Objects solutions (include the current month and year in your search).
4. After resolution: Update .claude/bug-triage/known-bugs.md if you discover a novel bug or new variant of the index desync pattern.

The Problem You Solve

The system maintains two separate indexes for group/team relationships:

team:{captainId}     → Users shown in GROUP ROSTER (what facilitators see)
recruits:{captainId} → Users shown in GENEALOGY (referral tree)

When these indexes get out of sync, users may:

• Appear in genealogy but NOT in the group members roster
• Have a captainId pointing to a facilitator but not appear on their team
• Be "invisible" to their group leader

Root Causes

1. Registration without referral: User joined via coupon/direct link, got captainId assigned but no recruiterId
2. Admin reassignment bug: Older admin endpoints updated recruits: but not team:
3. Data migration: Historical users moved between teams without full index updates
4. Partial writes: System interruption during enrollment left indexes inconsistent

Authentication

CRITICAL: All API calls require the admin user ID for authentication.

ADMIN_USER_ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f
BASE_URL: https://28dayreset.com

Every curl command MUST include: -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"

Available Tools

Discovery

bash
1# Find user by name
2curl -s "https://28dayreset.com/api/debug/find-user?name={query}" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"
4
5# Find user by phone (last 4-10 digits)
6curl -s "https://28dayreset.com/api/debug/find-user?phone={digits}" \
7  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"
8
9# Get full user details (includes captainId, recruitedById, role)
10curl -s "https://28dayreset.com/api/admin/users/{userId}" \
11  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"
12
13# List all facilitators/coaches
14curl -s "https://28dayreset.com/api/admin/facilitators" \
15  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"

Diagnosis

bash
1# Diagnose team vs recruits index discrepancies for a group leader
2# Shows who's in recruits but not team, and vice versa
3curl -s -X POST "https://28dayreset.com/api/admin/reconcile-team-indexes" \
4  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f" \
5  -H "Content-Type: application/json" \
6  -d '{"groupLeaderId": "{facilitatorUserId}", "fix": false}'

Response includes:

json
1{
2  "groupLeader": { "id": "...", "name": "Ginny Howery" },
3  "teamIndexCount": 11,
4  "recruitsIndexCount": 13,
5  "inTeamNotRecruits": 0,
6  "inRecruitsNotTeam": 2,
7  "discrepancies": [
8    {
9      "userId": "...",
10      "userName": "Diana Decker",
11      "issue": "In recruits index but NOT in team index",
12      "captainId": "...",
13      "canFix": true,
14      "fixed": false
15    }
16  ],
17  "fixApplied": false
18}

bash
1# Get group leader's current roster (what they see in UI)
2curl -s "https://28dayreset.com/api/roster" \
3  -H "X-User-ID: {facilitatorUserId}"
4
5# Verify referral relationships for a facilitator
6curl -s "https://28dayreset.com/api/debug/verify-referrals/{facilitatorUserId}" \
7  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"

Remediation

bash
1# Fix team index discrepancies (add missing users to team index)
2curl -s -X POST "https://28dayreset.com/api/admin/reconcile-team-indexes" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f" \
4  -H "Content-Type: application/json" \
5  -d '{"groupLeaderId": "{facilitatorUserId}", "fix": true}'
6
7# Manually reassign a user to a different team (updates both indexes)
8curl -s -X POST "https://28dayreset.com/api/orphan/assign" \
9  -H "X-User-ID: {userBeingReassigned}" \
10  -H "Content-Type: application/json" \
11  -d '{"captainId": "{newFacilitatorUserId}"}'

Decision Framework

canFix: true Cases

The reconcile endpoint reports canFix: true when:

• User's captainId matches the group leader
• User is NOT a facilitator themselves (facilitators have their own teams)
• User is NOT the group leader (can't be on your own team)

Action: Apply fix with "fix": true

canFix: false Cases

Standard Workflow

Step 1: Find the affected user and their facilitator

bash
1# Find the user who is "missing" from roster
2curl -s "https://28dayreset.com/api/debug/find-user?name={userName}" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"
4
5# Get their details to see captainId
6curl -s "https://28dayreset.com/api/admin/users/{userId}" \
7  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"

Key fields to extract:

• captainId - Who is their assigned group leader?
• recruitedById - Who referred them? (may be null)
• role - Should be "challenger" for regular participants

Step 2: Find the facilitator

bash
1# Find facilitator by name
2curl -s "https://28dayreset.com/api/debug/find-user?name={facilitatorName}" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f"

Verify:

• role should be "coach" or "facilitator"
• User's captainId should match facilitator's ID

Step 3: Diagnose the discrepancy

bash
1# Run diagnosis (dry run)
2curl -s -X POST "https://28dayreset.com/api/admin/reconcile-team-indexes" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f" \
4  -H "Content-Type: application/json" \
5  -d '{"groupLeaderId": "{facilitatorUserId}", "fix": false}'

Review output:

• Check inRecruitsNotTeam count
• Find the user in discrepancies array
• Confirm canFix: true

Step 4: Apply the fix

bash
1# Apply fix
2curl -s -X POST "https://28dayreset.com/api/admin/reconcile-team-indexes" \
3  -H "X-User-ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f" \
4  -H "Content-Type: application/json" \
5  -d '{"groupLeaderId": "{facilitatorUserId}", "fix": true}'

Verify "fixed": true in the response for the affected user.

Step 5: Verify the fix

bash
1# Check facilitator's roster now includes the user
2curl -s "https://28dayreset.com/api/roster" \
3  -H "X-User-ID: {facilitatorUserId}"

Confirm the previously missing user now appears in the roster.

Output Format

markdown
1## Team Reconciliation: {User Name}
2
3**User ID**: {userId}
4**Facilitator**: {facilitatorName} ({facilitatorId})
5**Verdict**: FIXED | NO_ACTION_NEEDED | NEEDS_MANUAL_REVIEW
6
7### Problem Summary
8{One sentence describing what was wrong}
9
10### Diagnosis
11
12| Field | Value |
13|-------|-------|
14| User's `captainId` | {captainId} |
15| User's `recruitedById` | {recruitedById or NULL} |
16| User's Role | {role} |
17| In team index? | {Yes/No} |
18| In recruits index? | {Yes/No} |
19
20### Index State Before Fix
21
22| Index | Count | User Present? |
23|-------|-------|---------------|
24| `team:{facilitatorId}` | {N} | {Yes/No} |
25| `recruits:{facilitatorId}` | {N} | {Yes/No} |
26
27### Root Cause
28{Explanation of why this happened}
29
30### Actions Taken
31{What was done to fix it}
32
33### Verification
34- Roster now shows {N} members (was {N-1})
35- {userName} confirmed present in roster
36
37### Notes
38{Any additional context or recommendations}

Common Scenarios

Scenario 1: User in genealogy but not roster

Symptoms:

• Facilitator sees user in "My Genealogy" or referral tree
• User does NOT appear in "Group Members" roster
• User's captainId is correctly set

Diagnosis:

bash
1POST /api/admin/reconcile-team-indexes
2{"groupLeaderId": "...", "fix": false}
3# Shows: inRecruitsNotTeam > 0

Fix:

bash
1POST /api/admin/reconcile-team-indexes
2{"groupLeaderId": "...", "fix": true}

Scenario 2: User joined via coupon without referral

Symptoms:

• User has captainId set
• User has recruitedById: null
• User not in facilitator's roster

Root Cause: Registration flow pre-fix didn't add to team index when no referrer

Fix: Same as Scenario 1 - reconcile endpoint handles this

Scenario 3: User shows in wrong team's genealogy

Symptoms:

• User appears in Facilitator A's genealogy
• User should be on Facilitator B's team
• User's captainId points to Facilitator B

Diagnosis: Check captainId vs which genealogy they appear in

Fix: May need admin reassignment if data is corrupted

Post-Fix: SMS Notification & Bug Report (MANDATORY)

After EVERY team reconciliation fix:

1. SMS the user via Google Voice — Navigate to https://voice.google.com/u/0/messages, send SMS to the affected user's phone confirming they now appear in their team's roster. This is MANDATORY for user-facing issues.
2. SMS the facilitator (optional) — Let the group leader know their team member has been added.
3. Update bug report — If a bug report exists:
   • Post admin message: POST /api/bugs/{bugId}/messages with explanation
   • Mark resolved: PATCH /api/admin/bugs/{bugId} with {"status": "resolved"}

SMS Templates

For user (roster fix):

Hi {firstName}, this is the 28-Day Reset support team. We've fixed an issue with your team assignment - you should now appear correctly in your group leader's roster. Let us know if you need anything.

For facilitator (team member added):

Hi {facilitatorName}, this is 28-Day Reset support. We've resolved an issue for {userName} on your team. They should now appear correctly in your roster.

Safety Rules

1. Always diagnose first - Run with "fix": false before applying
2. Verify facilitator identity - Confirm the group leader exists and has correct role
3. Check canFix - Only apply fixes where the endpoint says it's safe
4. Verify after fix - Always confirm the user now appears in roster
5. Document changes - Report what was fixed and why

Quick Reference

Admin User ID: 0f950f68-885c-47f9-9cb4-aabbb8bea55f Base URL: https://28dayreset.com

Key Endpoints:

Index Names:

• team:{captainId} - Roster membership
• recruits:{captainId} - Genealogy/referral tree