Agent Architect

Use this skill to diagnose where an agent problem belongs before changing anything.

This is a narrow architecture audit skill. It does not run a governance program, build a dashboard, or redesign the whole agent unless the evidence clearly earns that conclusion.

Recommendations from this skill are diagnostic only. Do not apply patches without reviewing whether the lane assignment and fix type actually match the problem.

Use when

• an agent sounds wrong, acts off-brand, or drifts in tone
• an agent keeps making the same operating mistake
• an agent forgets key context, commitments, or prior corrections
• an agent keeps solving repeatable problems ad hoc instead of through a skill or workflow
• the real question is which layer should change rather than how to patch the symptom
• deciding whether the fix belongs in SOUL.md, AGENTS.md / operations files, memory files, or a skill directory

Do not use when

• the user already knows the exact file and exact edit to make
• the task is routine skill authoring with no architecture diagnosis needed
• the request is to build a whole new agent system, dashboard, registry, or governance framework
• the issue is a one-off execution failure better solved by fixing the local task directly
• there is not enough evidence yet to distinguish signal from a single bad run

The four lanes

1. Persona / tone — identity, voice, style, stance, response texture
2. Rules — constitutional constraints, operating rules, decision protocols, escalation boundaries, workflow habits
3. Memory — what is stored, when it is written, how it is retrieved, where durable facts vs daily state live
4. Skills — reusable workflows, narrow procedural packages, tool-routing, repeatable playbooks

Read references/lane-diagnosis.md before assigning a lane.

Default workflow

1. Start from the symptom, not the fix Capture the failure pattern, repeated friction, or observed weakness.

2. Check whether this is recurring or isolated If it is a one-off, prefer a local fix or no change.

3. Assign the primary lane Read references/lane-diagnosis.md and choose the lane causing the failure. If multiple lanes contribute, name one primary lane and at most one secondary lane. Only recommend a secondary-lane patch if the primary-lane fix would clearly fail without it. Otherwise, note the secondary lane as context only.

4. Choose the smallest justified fix type Read references/fix-types.md and prefer, in order:

   • no change
   • plain edit
   • memory tweak
   • rule change
   • skill change

   Do not escalate to a larger fix just because it feels more architectural. Weak evidence should bias toward no change or a local edit. Structural changes need recurrence, cross-context benefit, or repeated operator friction.

5. Say where the patch belongs Point to the layer or file family directly:

   • persona → SOUL.md, identity/tone docs
   • rules → AGENTS.md, OPERATIONS.md, guardrails, QA/protocol docs
   • memory → MEMORY.md, memory/*.md, memory procedures, retrieval paths
   • skills → a specific skill's SKILL.md, references/, or a new narrow skill only if earned

6. State what not to touch Avoid collateral edits, broad rewrites, and cross-lane churn unless clearly necessary.

7. Use the output format exactly Keep the answer short, decisive, and patch-oriented.

8. Log meaningful architecture recommendations If the diagnosis leads to a real structural recommendation, log the lane, fix type, and short symptom summary to daily memory so future audits can see what changed and why.

For a fast pass before recommending any change, read references/audit-checklist.md.

Output format

Human-readable

1. Diagnosis — what is actually going wrong
2. Lane — persona / rules / memory / skills
3. Recommended fix type — plain edit / rule change / skill change / memory tweak / no change
4. Smallest justified patch — exact change and where it belongs
5. Risks / what not to touch — nearby changes that would be overreach

Structured option

diagnosis: short summary of what is actually wrong
lane: persona|rules|memory|skills
secondary_lane: none|persona|rules|memory|skills
fix_type: no_change|plain_edit|memory_tweak|rule_change|skill_change
patch_target: exact file or file family
smallest_patch: concise patch recommendation
risks:
  - overreach to avoid
  - adjacent file or lane not to touch

Works well with

• skill-builder — when the result is "tighten or add a narrow skill"
• memory-architecture skills such as cognition — when the issue is durable storage, retrieval shape, or memory-system design beyond a local tweak
• battle-tested-agent — when the diagnosis suggests reliability hardening patterns across memory, delegation, or verification
• openclaw-guide — when the issue is really OpenClaw routing, config, session behavior, or platform mechanics rather than the agent itself

References

• references/lane-diagnosis.md — how to identify the weak lane and avoid misclassification
• references/fix-types.md — how to choose the smallest justified intervention
• references/audit-checklist.md — fast audit pass before recommending any patch
• references/placement-map.md — where each kind of fix usually belongs
• references/worked-examples.md — compact examples for common mixed-lane failures and one do-nothing case

Output style

Be crisp. Route the problem to the right layer. Prefer the smallest justified patch over architectural theater.