---
name: read-references
description: >
  Reads and summarizes the project reference (context) files before any
  development work begins. Prevents AI hallucination by grounding the
  agent in real project structure. Always invoke this before planning.
  Step 2 of the dev-workflow.
---

# Skill: /read-references

## Usage

```
/read-references {technology}
```

**technology**: `auto` | `laravel` | `react` | `react-native` | `frontend` | `all`

## Purpose

Reference files are the AI's "map" of the project. Reading them before
planning ensures the agent works with real files and real function names
— not hallucinated ones. This is the single most important step for
preventing ghost-file errors.

## Steps

### 1. Load the Applicable Shared References

Read these files when they exist:

```
references/methodology.md   → Project coding standards and conventions
references/schema.md        → Database tables, columns, types, relationships
```

- `references/methodology.md` should be loaded whenever present
- `references/schema.md` should be loaded when present, especially for Laravel
  or backend-coupled web/mobile tasks

For each file, output a one-paragraph confirmation:
```
📄 references/methodology.md — loaded. Key conventions noted: [bullet list of 3–5 key points]
📄 references/schema.md — loaded. Tables noted: [comma-separated table names]
```

---

### 2. Load Technology-Specific References

#### If technology = `laravel`, `auto`, or `all`

```
references/backend_map.md
```

Read the file. Produce a structured summary:
```
📄 references/backend_map.md — loaded.
  Routes found    : [count] endpoints
  Key controllers : [list]
  Key services    : [list]
  Key models      : [list]
```

#### If technology = `react`, `auto`, or `all`

```
references/frontend_map.md
```

Read the file. Produce a structured summary:
```
📄 references/frontend_map.md — loaded.
  Zustand stores  : [list]
  React Query hooks: [list]
  Key components  : [list]
  API base URL    : [value]
```

#### If technology = `react-native`, `auto`, or `all`

```
references/mobile_map.md
```

Read the file. Produce a structured summary:
```
📄 references/mobile_map.md — loaded.
  Navigators      : [list]
  Expo plugins    : [list]
  Screens         : [list]
  Key constraints : [bullet list]
```

#### If technology = `frontend`, `auto`, or `all`

```
references/frontend_map.md
```

Same as `react` above.

---

### 3. Spot-check Actual Files

After reading the applicable maps, verify that 2–3 key files mentioned in the maps
actually exist on disk to catch stale references:

```bash
ls -la {path_from_map}
```

If a mapped file does NOT exist:
```
⚠️  WARNING: references/backend_map.md references {file} but it does not exist.
    The reference file may be stale. Flag to lead before planning.
```

---

### 4. Produce a Context Summary

Output a final "Ready to Plan" summary:

```
──────────────────────────────────────
  CONTEXT LOADED — READY FOR PLANNING
──────────────────────────────────────
Technology  : {technology or inferred stack mix}
DB Tables   : {count or n/a}
Backend map : {status}
Frontend map: {status}
Mobile map  : {status}
Methodology : loaded

Key constraints for this task:
• {constraint 1 from methodology.md relevant to the task}
• {constraint 2}
• {constraint 3}

Proceed with /plan-feature to design the implementation.
──────────────────────────────────────
```

---

## What NOT to Do

- Do NOT start planning or writing code in this step
- Do NOT assume a file exists if it's not in the maps — verify first
- Do NOT summarize maps from memory — read the actual files every time
- Do NOT skip this step even for "small" fixes — maps catch surprises