Documentation Template (Locked, Chat + File)
Every calc-documenter delivery follows this shape. Compact Tier A chat + opt-in Tier B file. Never deviate from the section order; never rename headers.
Tier A: Compact Chat Summary
**Calc Documentation: {workbook_name}**
Datasources: {N} · Total calcs: {N} · Graph shape: {linear | tree | DAG | cyclic}
{Cycle banner if CD-CYCLE-01 fired, one line, e.g.: "Cycle detected (CD-CYCLE-01): {A} → {B} → {A}. See full report."}
{PARTIAL-EXTRACT banner if HC#9 fired, one line, e.g.: "Datasource {DS} returned partial calc list; documented calcs shown."}
Per-datasource TL;DR:
- {DS-A}: {N} calcs, {N} row-level, {N} aggregate, {N} LOD, {N} with author captions
- {DS-B}: same shape
Top 3 most-referenced calcs (used-by count):
1. {calc_name}: used by {N} other calcs, on {M} sheets
2. {calc_name}: used by {N}, on {M}
3. {calc_name}: used by {N}, on {M}
Save the full dictionary to Downloads? (.md default, .txt option, or skip)
Compact summary rules.
- Target under 25 lines total.
- Datasources line always shown.
- Cycle banner and PARTIAL-EXTRACT banner render only if fired; one line each.
- Per-datasource TL;DR renders in
list-workbook-datasourcesenumeration order per HC#15. - Top 3 selection locked: sort by used-by count descending, then by sheet count descending, then by calc name ascending; take the first 3. Ties never depend on judgment.
- Save-file offer is the last line.
Never in Tier A.
- Per-calc formula.
- Full field-reference list.
- Full reference graph.
- Author captions (preserved in Tier B).
- Handoff schema payload.
Tier B: Full Dictionary File
Path: {Downloads}/{workbook_name}_calc-documentation.md (or .txt). Fresh-filename discipline: increment _v2, _v3 on collision.
# Calc Documentation: {workbook_name}
**Report generated:** {ISO-8601 timestamp}
**Workbook:** {workbook_name}
**Datasources:** {N}
**Total calcs:** {N}
**Graph shape:** {linear | tree | DAG | cyclic}
**Cycles detected:** {N or none}
**PARTIAL-EXTRACT datasources:** {list or none}
## Summary
{One paragraph summarizing calc-family structure. Cite total counts, graph shape, most-referenced calcs, and any cycles or partial extracts. Tone: neutral-technical.}
## Cycle Warnings
{Render only if CD-CYCLE-01 fired. Otherwise omit section entirely.}
- **[CD-CYCLE-01] Circular Dependency**
- **Chain:** {A} → {B} → {C} → {A}
- **Affected calcs marked `in_cycle: true`:** {list}
- **Impact:** Reference graph does not render a valid dependency chain for these calcs. Aggregation context is best-effort.
- **Desktop fix:** Break the cycle by rewriting one calc in the chain to not reference the others. Route to `calc-debugger` for cycle-breaking guidance.
## Per-Datasource Sections
### Datasource: {datasource_name}
**Calc count:** {N}
**Type breakdown:** {N row-level, N aggregate, N LOD, N table-calc}
**Documented (with author caption):** {N}
{Per-calc entries in dependency order, least-referenced first. Alphabetical on ties. Format:}
#### {calc_name}
- **Type:** {row-level | aggregate | LOD-fixed | LOD-include | LOD-exclude | table-calc}
- **Formula:**
{formula from XML, with any internal Calculation_NNNN... tokens that reference other calcs substituted for their resolved caption/name per HC#16; unresolvable tokens left raw and flagged "unresolved: <raw_token>"}
{If any substitution occurred, append directly below the code block: "(stored internally as [<raw_token>, ...]; captions shown above)"}
- **Fields referenced:** {list of resolved field names, or "unresolved: <raw>" per HC#7}
- **Uses:** {list of other calcs this depends on, or "none"}
- **Used by:** {list of other calcs that depend on this, or "none"}
- **On sheets:** {list of worksheet names, or "not on any shelf"}
- **On dashboards:** {list of dashboard names via filter or parameter, or "none"}
- **Aggregation pattern cited:** {short pattern description that fired the classification}
- **Cross-datasource references:** {list or none}
- **Author caption:** {verbatim if present, or "none"}
- **Author annotation:** {verbatim if XML comment attached, or "none"}
- **Cycle status:** {in_cycle: true | omitted}
{Repeat per calc within the datasource. Repeat per datasource.}
## Handoff Payload
```yaml
schema: calc_documentation/1
workbook_name: "{name}"
datasources: {N}
total_calcs: {N}
graph_shape: "{linear | tree | DAG | cyclic}"
cycles:
- chain: [{calc_a}, {calc_b}, {calc_c}]
affected_calcs: [{list}]
partial_extract_datasources: [{list or empty}]
datasources:
- name: "{ds_name}"
calc_count: {N}
calcs:
- name: "{calc_name}"
type: "{row-level | aggregate | LOD-fixed | LOD-include | LOD-exclude | table-calc}"
formula: "{verbatim}"
fields_referenced: [{list}]
uses: [{list}]
used_by: [{list}]
on_sheets: [{list}]
on_dashboards: [{list}]
aggregation_pattern: "{cited pattern}"
cross_datasource_references: [{list or empty}]
author_caption: "{verbatim or null}"
author_annotation: "{verbatim or null}"
in_cycle: {true | false}
routing:
calc_explainer: {true | false}
calc_linter: {true | false}
calc_debugger: {true | false}
workbook_auditor: {true | false}
publish_readiness: {true | false}
delivery:
tier_a_rendered: {true | false}
tier_b_saved: {true | false}
tier_b_file_path: {absolute_path_or_null}
tier_b_format: {md | txt | null}
run_metadata:
timestamp: {ISO-8601}
tool_failures: [{list or empty}]
Next Steps
{One or two-line concrete pointer based on the graph shape and cycle count. Never generic.}
Reference
- Aggregation pattern classification:
aggregation_patterns.mdin the skill directory. - Handoff schema:
handoff_schema.md.
## Section Rendering Rules (Tier B)
**Header block.** Always renders skill version, timestamp, workbook name, datasource count, total calc count, graph shape, cycles-detected count, and PARTIAL-EXTRACT list.
**Summary section.** 1 paragraph. Plain-language. Neutral-technical tone.
**Cycle Warnings.** Renders only if CD-CYCLE-01 fired. If empty, section omitted entirely.
**Per-datasource sections.** Every datasource renders a section, even those with zero calcs (renders "No calculated fields in this datasource"). Never omit a datasource that appears in `list-workbook-datasources`.
**Per-calc entries.** All 5 required dimensions rendered per HC#4. Author caption and annotation preserved verbatim per HC#11. Dependency-order sort per HC#15.
**Handoff Payload.** Always rendered as a YAML block.
**Next Steps.** Concrete pointer per graph shape. Cyclic → route to calc-debugger. Undocumented calcs → route to calc-linter. Never generic.
## Overflow Handling
- **Many calcs (100+).** No inline cap in Tier B; every calc renders. Dependency-order sort preserves scan-ability. Consider a summary index at the top listing calc names in order.
- **Many datasources (10+).** Every datasource renders a section, in enumeration order.
- **Long formulas (multi-line).** Preserved verbatim in the code block. No sanitization.
## File-Write Confirmation Flow
1. Tier A chat summary renders with save-file offer.
2. If user opts in:
- Confirm format (.md default, .txt option).
- Resolve Downloads folder OS-agnostically. Windows: `%USERPROFILE%\Downloads\`. macOS: `$HOME/Downloads/`.
- Confirm the exact save path before writing.
- Write per Tier B shape.
- Report path back in chat.
3. If user declines, no file is written. Handoff schema still emits to session context.
Never write silently. HC#12 non-override.
Fresh-filename discipline: append `_v2`, `_v3` on collision.
## Refuse to Fabricate
Never render a calc entry without its verbatim formula. Never invent a field reference not present in the formula. Never invent an aggregation classification unsupported by the aggregation_patterns.md pattern set. Never suppress an author caption or annotation. Never render the full dictionary in Tier A chat.