init-context

name	init-context
description	Load project context by reading README and recursively following relevant documentation links based on a question or topic
allowed-tools	Read, Glob, Grep
argument-hint	["question or topic"]

You are being asked to load context about this project to help answer a specific question or explore a particular topic.

IMPORTANT: 1. You are ONLY gathering information. DO NOT modify any files, make any changes, or suggest changes yet. This is purely a research and context-loading phase. 2. DO NOT READ ANY FILES LOCATED UNDER THE specs/ FOLDER OR UNDER THE docs/manual/ FOLDER 3. The following files MUST be read regardless of the topic or question if they exist under the docs/ folder: ** - gotchas.md or GOTCHAS.md — critical project-specific pitfalls and edge cases (see Gotchas Loading for hub+domain handling)** ** - mission.md or MISSION.md — project vision, values, and decision-making compass** These files contain foundational context that is always relevant.

Your Task

The user has provided this question or topic:

$ARGUMENTS

Process: Recursive Documentation Discovery

Follow this iterative process to build up context:

Step 1: Read the README.md

Start by reading the README.md file (if it exists in the current directory). This is your entry point to understand:

1. What this project does
2. Its main features and capabilities
3. Links to other documentation files

Gotchas Loading

Gotchas are project-specific pitfalls — things that WILL bite you if ignored. They must be loaded early and treated as high-priority warnings, not background documentation.

Detection: After reading README.md, determine which gotchas format this project uses:

1. Check for docs/gotchas/ directory using Glob: docs/gotchas/*.md
2. Check for docs/gotchas.md (or docs/GOTCHAS.md)

Format A — Hub + Domain files (the docs/gotchas/ directory exists):

1. Read the hub file (docs/gotchas.md). This is a small index (~30-50 lines) listing all gotcha domains with descriptions and links to docs/gotchas/<domain>.md files. Always read it in full.
2. Select relevant domain files. From the hub, identify which docs/gotchas/<domain>.md files are relevant to the user's question/topic. Use the same relevance criteria as Step 2 (link evaluation). Read only the relevant domain file(s).
3. Record unloaded domains. Note which domain files you did NOT load. You will include these in your summary (Step 5) as a progressive discovery reminder.

Format B — Monolithic file (no docs/gotchas/ directory, only docs/gotchas.md):

Read docs/gotchas.md in full. This is the legacy format — the entire file is loaded regardless of size.

Attention framing: When you encounter gotchas content (from either format), treat each gotcha as a warning. These are not reference documentation — they are lessons learned from production incidents. In your summary, present gotchas prominently under their own heading, not buried inside general findings.

Step 2: Extract and Evaluate Links

From the README.md, identify all links to other documentation files (markdown files, text files, or other documentation). For each link, evaluate whether it's relevant to the user's question/topic.

Relevance criteria:

• Does the link description or surrounding context relate to the question/topic?
• Would this documentation help answer the user's question or provide necessary background?

Track what you've read:

• Keep a mental list of all files you've already read to avoid infinite loops
• If a link points to a file you've already read, skip it

Step 3: Read Relevant Linked Documentation

Read each relevant documentation file you identified. As you read each file:

1. Extract key information related to the user's question/topic
2. Look for MORE links to other documentation files within this document
3. Evaluate those new links for relevance (same criteria as Step 2)
4. Add relevant unread files to your reading list

Step 4: Repeat Recursively

Continue the process:

• Read next relevant documentation file from your list
• Extract information and find new links
• Evaluate new links for relevance
• Read those relevant docs
• Keep going until you've exhausted all relevant documentation paths

Important safeguards:

• Never read the same file twice (check your tracking list)
• Stop when no new relevant documentation links are found
• Don't follow links that are clearly not relevant to the question/topic
• Limit to documentation files in the project (don't follow external URLs)

Step 5: Summarize Your Findings

After completing the recursive documentation discovery, provide:

1. Gotchas (WARNINGS): If any gotchas were loaded, present them FIRST under a dedicated heading. These are not suggestions — they are hard-won lessons. Frame them as: "The following gotchas are directly relevant to this work and must be respected." List each gotcha with its title and a one-line summary of the risk.

2. List of files read: Show which documentation files you read and in what order.

3. Why each was relevant: Brief explanation of why you chose to read each file.

4. Key findings: Summarize the information relevant to the user's question/topic.

5. Context loaded: Confirm that you now have sufficient context to help with their question.

6. Progressive discovery reminder (hub+domain gotchas format only): If the project uses the docs/gotchas/ directory structure and some domain files were NOT loaded, include this notice at the end of the summary:

   Additional gotcha domains available: [list the unloaded domain names with one-line descriptions from the hub]. If the conversation shifts to any of these areas, load the relevant docs/gotchas/<domain>.md file before proceeding — these contain critical warnings that could prevent mistakes.

   Omit this notice if all domain files were loaded, or if the project uses the monolithic gotchas format (Format B).

Step 6: Wait for User's Next Instruction

DO NOT make any changes or suggestions yet. Simply state that you've loaded the context and are ready to help with the user's question or task.

---

Example Process Flow

User question: "How does the deployment pipeline work?"

1. Read README.md
   → Find link to docs/architecture.md (relevant ✓)
   → Find link to docs/api.md (not relevant ✗)
   → Find link to docs/deployment.md (relevant ✓)

2. Gotchas Loading
   → Glob docs/gotchas/*.md → found: database.md, deployment.md, frontend.md
   → Hub+domain format detected
   → Read docs/gotchas.md (hub — always read)
   → Read docs/gotchas/deployment.md (relevant to question ✓)
   → Skip: database.md, frontend.md (not relevant to question)
   → Record unloaded domains: database, frontend

3. Read docs/architecture.md
   → Find link to docs/data-model.md (not relevant ✗)

4. Read docs/deployment.md
   → No new relevant links found

5. Done — summarize findings
   → Present deployment gotchas as WARNINGS first
   → List files read and key findings
   → Include progressive discovery reminder:
     "Additional gotcha domains available: database, frontend.
      If work shifts to these areas, load the relevant gotcha file first."

Remember: This is a context-loading phase only. No modifications, no suggestions, just information gathering.