# CR-001: Content Structure & Navigation

| Field | Value |
|-------|-------|
| CR ID | CR-001 |
| Feature | FEATURE-051-A |
| Epic | EPIC-051 |
| Classification | modification |
| Priority | Medium |
| Date | 03-17-2026 |
| Requestor | User (product owner) |

## Change Description

Optimize user manual templates with 5 structural improvements:
1. **Table of Contents (ToC)** — Add a content section at the top of the playbook that links to different scenarios/sections. Acts as navigation.
2. **Content splitting for large playbooks** — Estimate content size. If the assembled playbook would exceed 800 lines, each scenario/section should be a separate sub-markdown file rather than inline.
3. **Cross-file linking in ToC** — ToC should link to both inline sections in the main playbook AND separate sub-markdown files when content is split.
4. **Scenario-level markdown** — Each scenario sub-file should have an instructions section explaining how to use that scenario, plus support for images/screenshots of the UI.
5. **Naming conventions** — Both sub-markdown files and images within scenarios should follow naming conventions.

## Business Justification

Real-world user manuals for complex applications can be large. Without ToC and content splitting, the output becomes unwieldy. Industry-standard documentation tools (GitBook, MkDocs, Docusaurus) all use ToC + file splitting + naming conventions.

## Impact Analysis

- **Affected files:** playbook-template.md, SKILL.md (pack_section operation)
- **No conflicts:** Additive changes only
- **Scope:** Small — single feature, additive ACs
- **Risk:** Low — no existing functionality changed

## New ACs Added

AC-051-07a through AC-051-07f (Content Structure & Navigation group)

## Changes Made

### 1. specification.md
- Added Version History entry: v1.1 | 03-17-2026 | CR-001: Add ToC, content splitting, cross-linking, scenario instructions, naming conventions
- Updated version to v1.1
- Added AC-051-07 group with 6 new acceptance criteria (AC-051-07a through AC-051-07f)

### 2. playbook-template.md
- Added Table of Contents section at the top with inline and split mode examples
- Added Content Splitting Guidelines section at the end with:
  - 800-line threshold guidance
  - File naming conventions for sub-files and images
  - Sub-file structure template
  - Decision criteria for when to split

### 3. SKILL.md
- Updated pack_section operation to add split_mode parameter (boolean, default false)
- Added logic for creating standalone sub-markdown files with Instructions and Screenshots sections
- Added naming convention enforcement per Content Splitting Guidelines

### 4. Candidate files
- Synced updated SKILL.md and playbook-template.md to candidate folder

## Backward Compatibility

All changes are backward compatible:
- Default split_mode=false preserves existing inline behavior
- ToC is additive, doesn't break existing structure
- Naming conventions apply only when split mode is enabled
- No breaking changes to operations API
