Feature Area

Documentation

Is your feature request related to a an existing bug? Please link it here.

Hi, and thanks for CrewAI — the “crew” abstraction is a very intuitive way for people to think about multiple agents working together.

I am the maintainer of WFGY, an MIT-licensed framework that captures 16 common failure modes for RAG systems and multi-agent workflows (hallucination, retrieval drift, long-chain collapse, multi-agent chaos, bootstrap ordering issues, etc.):

• WFGY ProblemMap (16-problem taxonomy, with docs):
  https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md

This map has already been referenced by:

• Harvard MIMS Lab – ToolUniverse (LLM tools benchmark)
• QCRI LLM Lab – Multimodal RAG Survey
• University of Innsbruck – Rankify project

Right now, many CrewAI users build fairly complex multi-agent setups (research / planning / coding crews), but when something goes wrong it is hard to name which failure mode they are hitting. From what I see in issues and community posts, a lot of problems fall almost perfectly into the WFGY 16-problem taxonomy (e.g. “multi-agent chaos”, “memory coherence”, “retrieval drift”, “bootstrap ordering”).

So the feature request is:

Add an official debugging guide in the CrewAI docs that maps common CrewAI failure patterns to the WFGY 16-problem map, with concrete examples for multi-agent setups.

Describe the solution you'd like

I would love to see a short “Debugging multi-agent crews with a 16-problem checklist” page in the docs.

Roughly:

1. Start from a simple table with three columns:
   WFGY problem (No.1–No.16) → CrewAI symptom → Suggested fix / pattern.
2. Focus on the problems that are most common for CrewAI:
   • No.1 / No.4: hallucination / overconfident agent responses.
   • No.3 / No.9: long-chain or entropy collapse in deep workflows.
   • No.7 / No.10: memory breaks and “creative freeze” in multi-step tasks.
   • No.13: multi-agent chaos (role drift, agents overwriting each other).
3. Add one or two minimal crew examples where you show
   • what the “broken” behaviour looks like, and
   • what changes (tooling, routing, memory, guardrails) fix it.

If this sounds aligned, I’m happy to draft an initial markdown doc that reuses the WFGY ProblemMap language but is written entirely in CrewAI terms (examples with Crew, Agent, Task, Process etc.), so you can review and adapt it to your style.

Describe alternatives you've considered

Right now the alternatives are:

• Every user builds their own ad-hoc checklist for debugging multi-agent runs.
• I keep WFGY as a separate repo and people have to read it side-by-side with CrewAI docs, then manually map problems to their own setups.

Both work, but they create extra friction. A short, official guide inside the CrewAI docs would make it much easier for users to recognise patterns like “this is No.13 multi-agent chaos, not just prompt tuning” and jump directly to the right fix.

Additional context

Some context if helpful:

• WFGY is MIT-licensed and designed to be framework-agnostic, so you can freely adapt the wording and diagrams into CrewAI docs.
• The same 16-problem map is already used by:
  • Harvard MIMS Lab (ToolUniverse),
  • QCRI LLM Lab (Multimodal RAG Survey),
  • University of Innsbruck (Rankify RAG toolkit).
• I’m actively using this map to debug RAG + multi-agent systems, so I can propose a first draft that is concrete (log snippets, typical traces, “what users actually see”) rather than just high-level theory.

If you think this would be more useful as a “How-to” tutorial or a “Best Practices” chapter instead of a single page, I’m happy to structure it that way too.

Willingness to Contribute

Yes, I'd be happy to submit a pull request