---
description: Citation format standards for framework recommendations
version: "1.1"
created: 2025-12-18
source: STORY-101, STORY-102
---

# Citation Requirements for Framework Recommendations

Technology and architecture recommendations MUST cite authoritative sources to enable verification, build trust, and maintain accuracy.

## Citation Format Templates

### 1. Framework File Citations
**Format:** `(Source: {relative-path}, lines {start}-{end})`
**Example:** TypeScript is required for all new code (Source: devforgeai/specs/context/tech-stack.md, lines 12-14)
**Rules:** Path relative to project root (no leading `./`), line range ≤20 lines, file must exist and be readable, cited lines must support the recommendation.

### 2. Memory File Citations
**Format:** `(Source: {relative-path}, section {section-identifier})`
**Example:** The /dev command uses TDD workflow (Source: .claude/skills/spec-driven-dev/SKILL.md)
**Rules:** Section identifier matches actual heading in file, use heading text or numbered format (e.g., "3.2"), path follows `.claude/memory/*.md` pattern.

### 3. Code Example Citations
**Format:** `(Source: {file-path}, lines {start}-{end})`
**Example:** Follow this test pattern (Source: devforgeai/tests/STORY-041/test-ac1-directory-structure.sh, lines 44-60)
**Rules:** Line range ≤50 lines for code citations, cited content must match example shown, larger examples require multiple citations.

## MUST Cite Categories (Blocking)

| Recommendation Type | Required Source |
|---------------------|-----------------|
| Technology decisions | `devforgeai/specs/context/tech-stack.md` |
| Architecture decisions | `devforgeai/specs/context/architecture-constraints.md` |
| Anti-pattern warnings | `devforgeai/specs/context/anti-patterns.md` |
| Source tree guidance | `devforgeai/specs/context/source-tree/` |

A recommendation in these categories MUST carry a line-specific citation. A technology/architecture recommendation not documented in the context files cannot be made — HALT and use AskUserQuestion instead.

## SHOULD Cite Categories (Recommended)

| Recommendation Type | Suggested Source |
|---------------------|------------------|
| Coding patterns | `devforgeai/specs/context/coding-standards.md` |
| Workflow guidance | `.claude/skills/*/SKILL.md` |
| Command usage | `.claude/commands/*.md` |

## Validation Rules
- **File paths:** Relative to project root, forward slashes only
- **Line numbers:** Positive integers, start ≤ end
- **Placement:** Citation within 2 lines of recommendation
- **Sensitive files:** Never cite `.env`, `*secret*`, `*credential*`, `*password*` files

## Grounding Protocol (Read-Quote-Cite-Verify)

Before making a technology/architecture recommendation:

1. **Read** — `Read(file_path="...")` the source file.
2. **Quote** — extract the exact word-for-word passage (minimum 2 lines) that supports the recommendation.
3. **Cite** — reference the source using a format above.
4. **Verify** — confirm the recommendation matches the quoted content. If Read fails or the content does not support it, do not proceed.

### Provenance Integration

Findings produced through this 4-step protocol are **GROUNDED**. Findings where Verify fails or evidence is ambiguous are **INCONCLUSIVE**. Recommendations made without completing all 4 steps are **DERIVED** and require a one-sentence justification. See `.claude/rules/core/epistemic-integrity.md`.
