Troubleshooting

Common Issues

”I don’t know which workflow to use”

Solution: Run cat-help. It analyzes your project’s current state and recommends the next workflow. You can also ask cat-master (Janus) to route you.

”The workflow can’t find my artifacts”

Likely cause: Artifacts aren’t in the expected location.

Solution: Check that artifacts are in _cat/artifacts/ with the correct subfolder:

_cat/artifacts/
├── intent/          # Intent Statements, Briefs, Features
├── architecture/    # ARC, AI Validation, Readiness Reports
├── construction/    # Bolt Specs, Code Reviews, Test Plans
└── validation/      # Adherence Reports, Compliance Reports

“The ARC Builder asks questions I already answered”

Likely cause: The Intent Brief isn’t linked or the workflow can’t locate it.

Solution: Ensure your Intent Brief is saved in _cat/artifacts/intent/. When starting cat-arc-builder, mention the specific Intent Brief: “Build an ARC based on the password-reset intent brief."

"Compliance Report shows gaps I’ve already addressed”

Likely cause: Artifacts exist but don’t have the expected structure or frontmatter.

Solution:

1. Check that artifacts have YAML frontmatter with status fields
2. Ensure ARC has explicit MUST/MUST NOT constraints (not just prose)
3. Verify bolt specs reference specific ARC constraint IDs

”Party Mode doesn’t include the agent I expected”

Likely cause: CAT selects agents based on the topic. Not all agents participate in every roundtable.

Solution: Explicitly request the agent: “Include Argus in this roundtable — I want SRE perspective on monitoring."

"Bolt execution produced code that doesn’t match our patterns”

Likely cause: CAT doesn’t know your project’s patterns.

Solution: Run cat-generate-project-context to create a project context file. This provides all CAT workflows with your codebase conventions, patterns, and rules.

”Quick Intent/ARC feels too lightweight for this change”

Solution: The Quick workflows are designed for small changes. If the scope grew:

1. The Quick Intent artifact is still valid — use it as input to cat-intent-brief
2. The Quick ARC can be expanded — use cat-arc-edit to add detail
3. Or start fresh with the full flow: cat-intent-statement → cat-intent-brief → cat-arc-builder

See Choosing Your Track for guidance.

Getting Help

Method	When to Use
cat-help	Context-aware guidance based on your project state
cat-master	Ask Janus to route you to the right workflow
cat-dlc-status	See what artifacts exist and what’s missing

Reporting Issues

If you encounter a bug in CAT itself (not a workflow question), file an issue in the CAT repository with:

1. The workflow you were running
2. The error or unexpected behavior
3. Your _cat/ folder structure (run tree _cat/ to generate)

---

See Also: Getting Started · Workflow Map · Configuration