new-doc

name	new-doc
description	Create a new documentation file in docs/ following this repo's standardized templates for advanced_topic, core_architecture, and implementation_plan doc types. Use when the user asks to write/create new documentation, a design doc, an architecture guide, or an implementation plan.

Create a new doc under docs/ matching one of this repo's three existing doc types. Do not invent a fourth structure — pick the closest of the three below. If $type is missing or doesn't match one of the three, ask the user which type fits before writing anything.

Choosing type and location

Type	When to use	Directory	Filename pattern	Example
advanced_topic	Deep dive on a single algorithm/subsystem's math or control theory (equations, physics, tuning theory)	docs/advanced_topics/	PascalCase.md	ShotCalculatorEquations.md
core_architecture	Explains a structural pattern used across the codebase (how subsystems/IO/state machines are organized)	docs/core_archictecture/ (keep the existing typo — renaming breaks links)	PascalCase.md	SubsystemArchitecture.md
implementation_plan	A concrete plan to implement a specific feature/issue, with file-by-file changes	docs/implementation_plans/	kebab-case-implementation-plan.md, reference the issue number in the title if one exists	alerts-implementation-plan.md

Before writing, grep the relevant source files (Grep/Glob) so the doc's code examples and API references are accurate to the current codebase, not guessed.

Template: advanced_topic

# [Topic Name]

[One sentence: what this document explains and which source file(s) it documents, e.g. "This document visualizes the equations used in `X.java` for Y."]

---

## 1. [First concept/equation]

[Equation in LaTeX ($$...$$) or code, followed by a "Where:" list defining each symbol with units.]

## 2. [Next concept]
...

[Continue numbered sections, each one equation/step, each followed by a "Where:" definitions list and, where non-obvious, a **Physical meaning:** line explaining why the math is shaped this way.]

---

## Complete Data Flow Diagram

[ASCII diagram showing how the inputs flow through the numbered steps to the outputs.]

---

## Coordinate Frames

[Only if spatial: define reference frames, origin, rotation direction.]

## Units

| Variable | Unit |
|----------|------|
| ... | ... |

Template: core_architecture

# [Pattern Name] Guide

[One paragraph: what structural pattern this explains and why it exists.]

---

## Table of Contents

1. [Overview](#overview)
2. [section links matching the headers below]

---

## Overview

[ASCII layered diagram of the pattern, plus attribution if adapted from a known FRC team's architecture.]

---

## [Pattern Section 1, e.g. "The IO Layer Pattern"]

### Purpose
[Why this piece exists.]

### Components
[Real code examples pulled from the actual source files — interface definition, then a real vs. sim implementation side by side.]

## [Pattern Section 2, e.g. "State Machine Pattern"]
[Same structure: purpose, then real code from the codebase.]

... [Repeat one section per structural concept in the pattern.]

---

## Complete Code Structure

[One full annotated example file showing every section a file of this type contains, with `// ========== SECTION ==========` banner comments.]

### Code Organization Rules

| Section | Contents |
| --- | --- |
| ... | ... |

---

## Data Flow

[ASCII diagram of the runtime call sequence, e.g. periodic() loop order.]

---

## File Organization

[Directory tree of where these files live, plus a naming conventions table: Pattern | Usage | Example.]

---

## Key Principles

[Short numbered list of the design principles this pattern enforces, e.g. Single Responsibility, Dependency Inversion.]

## Common Patterns

[Named sub-patterns worth calling out individually, each with a short code snippet — e.g. "Pattern: Supplier-Based Dynamic Setpoints".]

---

## Summary

| Layer/Component | Responsibility | Files |
| --- | --- | --- |
| ... | ... | ... |

Template: implementation_plan

# [Feature Name] Implementation Plan (Issue #[number])

## Goal

[What this implements and why, in 1-3 sentences. If the source issue lists distinct pillars/requirements, enumerate them.]

---

## [API/Pattern Reference section(s), one per relevant vendor library or existing code pattern]

[e.g. "## WPILib Alert API (existing pattern from `X.java`)" — show the existing pattern being extended, with a real code snippet from the codebase.]

### [Hardware/Library Variant, e.g. "TalonFX (CTRE Phoenix 6)"]
Used by: [list of subsystems]

#### [Sub-capability, e.g. "Connectivity check"]
[Exact API call, code snippet, and any caveats — bus traffic cost, update frequency, gotchas found while researching.]

... [Repeat per hardware variant / library used across the affected subsystems.]

---

## [Conditions/Detection table, one per hardware variant]

| Alert/Condition | Detection Method |
|---|---|

---

## Implementation Plan

### Step 1 — [short verb phrase]

[Instructions, followed by a file-change table:]

| File | Change | Notes |
|---|---|---|

### Step 2 — [short verb phrase]
...

[Repeat one numbered step per logical unit of work. Each step should be independently completable/testable.]

---

## [Tunable Values table, if applicable]

| Subsystem | Value | Threshold |
|---|---|---|

---

## File Change Summary

| File | Change |
|---|---|

---

## Implementation Order

[Numbered recommended sequence — easiest/lowest-risk first, so partial progress is always mergeable. Explain briefly why this order.]

After writing

• Save to the path determined above.
• Report the file path and a one-line summary of what was written back to the user.
• Do not add the new doc to any index/README unless one already exists and already lists sibling docs of the same type.