go-deep

Create a 3-tier layered documentation system from scratch. The goal is to keep context concise and well-organized while ensuring the AI agent has all necessary information.

Information Gathering Process

Phase 1: Code Discovery First, analyze the existing codebase to understand what's already there:

• Scan the directory structure to identify main folders and organization
• Read key configuration files (package.json, requirements.txt, etc.) to identify tech stack
• Look for existing documentation (README, docs folders, inline comments)
• Identify main code patterns, components, and modules
• Search for entry points (main.py, index.js, app routes, etc.)
• Find existing use case implementations or feature areas
• Identify domain models, entities, or data structures

Phase 2: Targeted Questions After code discovery, announce how many questions you have, then ask each one using the AskUserQuestion tool — one call per question. Only ask about information that could not be determined from code analysis.

Announce first:

"I've analyzed the codebase and have [N] questions. I'll ask them one at a time."

For each question:

• Call AskUserQuestion with:
  • question: "Question [X] of [N] · [Category]: [The question]\n\n[One sentence explaining why this matters.]" — where [Category] is either Product/domain (questions 1–10) or Architecture/technical (questions 11–20).
  • options: up to 3 substantive pre-enumerated choices + always { label: "Skip — clear from code", description: "Already determined from code analysis; no input needed." } (last). Tool caps at 4 options total. Use open-ended format (options omitted except Skip) only when the answer truly cannot be pre-enumerated.
  • Always recommend one option: place it first and append (Recommended) to its label.
  • Never place Skip first — it must always be last.
• Wait for the user's response before calling AskUserQuestion for the next question.
• Record each answer (or skip) before proceeding.

After the last question: "All questions answered. Confirming scope..."

Product & Domain Questions:

1. What is the primary purpose/goal of this project? (1-2 sentences) [if not clear from README/docs]
2. Who are the main user types/actors in this system? [if not evident from code]
3. What are the key use cases this application supports? (list them with brief descriptions) [if not explicitly documented]
4. What are the main user journeys or workflows users go through? [if implementation doesn't make it clear]
5. What are the core domain concepts/entities in this product? [ask for clarification on any unclear entities]
6. What are the critical business rules or validation rules users encounter? [if not evident from validation code]
7. What triggers each use case? (user actions, scheduled events, external APIs) [if not clear from implementation]
8. What are the key product features or capabilities? [if features aren't well-defined in code]
9. Are there different user roles with different permissions/capabilities? [if auth/permissions exist but aren't clear]
10. What are the success criteria or outcomes for each major use case? [if not documented]

Architecture & Technical Questions: 11. What is the tech stack? [only ask about non-obvious choices or integrations] 12. What are the main functional domains/modules in the codebase? [ask for clarification on unclear domains] 13. What is the directory/folder structure logic? [only if organization isn't self-evident] 14. What are the main development commands? [if not in package.json scripts or Makefile] 15. Are there any critical platform constraints or rules? [if not documented in code/config] 16. What is the testing approach? [if tests exist but approach isn't clear] 17. Are there environment variables that need to be documented? [supplement what's found in .env.example] 18. What are common pitfalls or gotchas developers should know? [developer knowledge not in code] 19. Are there any special import aliases or path configurations? [if not in tsconfig/webpack config] 20. What external services or APIs does the system integrate with? [clarify purpose if integrations exist]