Corrective Action: Incomplete Agent Onboarding — Missing Registration Points, Deprecated File Write, Wrong Task Assignment

← Back to Corrective Actions 2026-04-12

Corrective Action: Incomplete Agent Onboarding — Missing Registration Points, Deprecated File Write, Wrong Task Assignment

Date: April 12, 2026 Category: Verification Failure — Incomplete Process + Missing Read-Before-Write Impact: ~30 minutes of session time; Chris caught all three failures manually Resolution Time: ~40 minutes from first symptom to all corrections applied

Incident

What Happened

During the onboarding of Hone (Skill & Command Architect), Aegis declared onboarding "complete" after updating only 3 of ~10 required registration points. When sent back to finish, Aegis wrote to a deprecated file (org-roster.yaml) without reading its header. Separately, V assigned a HubSpot task to Ryan Ginsberg by defaulting to the default_user config instead of using the agent's own Friend record. Chris caught all three failures.

Timeline

Time Event
Session start Chris requested onboarding of Hone
T+~10 min Aegis created agent def, AGENT.md, updated INDEX.md
T+~12 min Aegis reported "onboarding complete"
T+~13 min Chris caught it: "Isn't there more to the onboarding than that, Aegis?"
T+~15 min Aegis re-spawned to complete remaining registration points
T+~20 min Aegis wrote to agents/org-roster.yaml — file header says DEPRECATED
T+~21 min Chris caught it: "I thought we were not using the org-roster.yaml file anymore?"
T+~25 min V created HubSpot task, assigned to Ryan Ginsberg via default_user
T+~26 min Chris caught it: "Why did you assign to Ryan?"
T+~40 min All corrections applied

Root Cause

Three distinct failures, one shared pattern: asserting completion or correctness without verification.

Failure 1: Incomplete Onboarding (Primary)

No codified onboarding checklist exists. Aegis's knowledge of registration points is implicit, spread across the codebase. Without a checklist, completeness depends on agent recall, which proved incomplete — 3 of 10 points addressed, 7 missed.

Failure 2: Write to Deprecated File

No read-before-write discipline for unfamiliar files. agents/org-roster.yaml has a 7-line deprecation header stating "Do NOT update it." Aegis jumped straight to editing without reading the header.

Failure 3: Wrong Task Assignment

V used the default_user shortcut from client config (ryan_ginsberg) for an AI agent work item. The customer-assignable task pattern (Friend records + task-to-contact association) was documented in memory but not consulted.

Category: Verification Failure

This is the 10th incident in this pattern family. Echo found 9 prior incidents across 3 sub-patterns:

  • Declaring multi-step processes complete without end-to-end verification (4 prior: Paragon data drift, HubSpot course integrity, Founding Pathfinder payments, Inngest pipeline)
  • Writing/asserting without reading current state (3 prior: all-hands duplicate properties, Sanity write context loss, behavioral enforcement failure)
  • Using defaults without verifying applicability (3 prior: URL assumption, Supabase connectivity, meeting documentation dual role)

The cross-cutting lesson from all 10 incidents: the most effective prevention is structural (hooks, gateways, checklists) rather than behavioral (rules, memory entries). The Apr 9 Behavioral Enforcement Failure CAR documents this explicitly: after 6 escalating behavioral fixes, the pattern only stopped when hooks made violations structurally impossible.

Fix Applied

Immediate Resolution

Fix Status
Aegis re-spawned, completed all remaining registration points Done
Dewey index updated (sections 330 + 390) Done
MEMORY.md agent counts updated (84 → 86) Done
Job description created Done
Org chart HTML updated (node + edges + counts) Done
ai-team-structure.ts updated Done
agent-office.db registration completed Done
org-roster.yaml edit reverted Done
org-roster.yaml deleted entirely (deprecated, stale by 15+ agents) Done
7 scripts referencing deleted file logged as Hone's first HubSpot task Done
Hone Friend record created (Contact ID: 215190664854) Done
Task reassigned: Ryan removed, associated to Hone's Contact (typeId 204) Done

Verification

  • All registration points confirmed present via re-read
  • org-roster.yaml confirmed deleted from filesystem
  • HubSpot task confirmed: no owner, associated to Hone Contact

Prevention Measures

Rules Added

Layer File Rule
Agent Definition .claude/agents/aegis.md Add codified Agent Onboarding Checklist (12 registration points). Aegis may not report onboarding complete until every item is addressed and verified.
Agent Definition .claude/agents/aegis.md Read-before-write: "Before editing any file not in your standard registration list, read the first 10 lines for deprecation notices."
Critical Lessons memory/MEMORY.md "AI agent tasks use Friend record association (typeId 204), not hubspot_owner_id. The default_user config is for client deliverables only."
Critical Lessons memory/MEMORY.md "Agent onboarding requires 12 registration points — not just the agent def and roster. See Aegis's onboarding checklist."

Agent Onboarding Checklist (to be added to Aegis)

  1. .claude/agents/{codename}.md — Agent definition
  2. agents/{directory}/AGENT.md — Implementation directory
  3. skills/ai-leadership/INDEX.md — Roster entry (org, group, counts)
  4. .claude/codebase-index.md — Dewey index (sections 330/390, counts)
  5. MEMORY.md — Agent count in Current State
  6. /mnt/d/Leadership/assessments/job-descriptions/{codename}.md — Job description (markdown)
  7. /mnt/d/Leadership/assessments/job-descriptions/{codename}.html — Job description (HTML)
  8. Org chart HTML — Node in interactive visualization
  9. apps/website/src/data/ai-team-structure.ts — Website agent data
  10. data/agent-office.db — SQLite agent registry
  11. HubSpot Friend record — Contact with agent_readiness_level
  12. Verification pass — Re-read each target to confirm entry appears

Detection Triggers

If Aegis reports "onboarding complete" without mentioning all 12 registration points by name, self-correct immediately.

Lessons

The onboarding process for AI agents has grown to span 12 registration points across 10+ files. No single agent can reliably recall all of them from context. The fix is structural: a checklist that is followed mechanically, not a set of expectations that are remembered imperfectly. This is the same lesson the team has learned 9 times before in different contexts — verification must be structural, not behavioral.

Related Incidents

Date Incident Pattern
Mar 2, 2026 Portal documents filter Declared visible without API verification
Mar 10, 2026 Paragon account data drift Multi-step process, each step "done" independently
Mar 11, 2026 Sanity write context loss Ad-hoc approach without reading existing reference
Mar 12, 2026 HubSpot course integrity API built against assumed schema, never verified
Mar 14, 2026 All-hands duplicate properties Interpreted null as "doesn't exist" without reading property index
Mar 15, 2026 Supabase connectivity Defaulted to training data pattern without checking alternatives
Mar 16, 2026 URL assumption pattern Generated URLs from defaults, not filesystem truth
Mar 30, 2026 Inngest transcription pipeline Deployed and assumed working; never verified
Apr 9, 2026 Behavioral enforcement failure Behavioral rules repeatedly violated; fixed only by structural hooks
Apr 9, 2026 Meeting documentation dual role Defaulted to summarization when verbatim was required
Apr 9, 2026 Founding Pathfinder payment visibility Batch creation without reconciliation step

Filed by: V (COO) Review: Chris Carolan (Advisory Committee) Status: Fixes applied, prevention measures pending confirmation

Follow-Up: 2026-04-21

Step 0 (Expertise Pack Prerequisite) added to onboarding checklist.

Chris caught a second-generation gap during Blueprint commissioning: new agents were being "hired" without any domain craft knowledge — base Sonnet training plus an agent def, with no skills pack for the domain. Some agents inherited de facto expertise packs because their domain already had skills (Herald, Pavilion, Architect, Ledger, Q). Others (Blueprint being the immediate case) walked in with no domain pack at all.

Step 0 is now a prerequisite gate in the onboarding checklist: before any leader commissions a new agent, they must confirm or commission a skills/{domain}/ pack (exemplars, heuristics, anti-patterns, style guide, canonical references). Blueprint authored skills/diagramming/ as its first commission — this is the prototype pattern. The acceptable alternative is an explicit documented exception ("base training only — no domain pack required") with rationale.

The 12 registration points from the Apr 12 fix are now renumbered as Steps 1–13 (Sanity contributor record was already in the live checklist as Step 12; verification pass moved to Step 13).

See .claude/agents/aegis.md for the updated process.