tomevault-io documentation
Purpose
Bridges the gap between technical planning and organizational approval. This skill synthesizes the output of idea (Requirements) and plan (Blueprints) into a professional "Leadership Package". It ensures that stakeholders have a clear, non-technical view of the work while providing engineers with importable Jira tickets.
Triggers
- User explicitly runs
/topia documentation - Automatically suggested after
planoradversary - User asks for "Jira tickets", "CSV", or "stories"
Calls (outbound)
idea(L2): readrequirements.mdfrom feature folderplan(L2): readplan.mdand phase files from feature folderadversary(L2): readadversary-report.mdwhen available for risk summary
Called By (inbound)
build(L1): when leadership package needed before implementationplan(L2): when plan output needs stakeholder-ready artifacts- User:
/topia documentationdirect invocation
Workflow
Phase 1: Context Intake
- Identify Target: Locate the active feature folder in
.topia/features/<name>/. - Read Inputs:
- Load
requirements.md(fromidea). - Load
plan.mdand phase files (fromplan). - Load
adversary-report.md(if available).
- Load
Phase 2: User Story Generation
- Draft Stories: Convert phase tasks into Agile User Stories.
- Format:
As a <role>, I want to <action>, so that <value>. - Criteria: Map each phase's Acceptance Criteria to its corresponding story.
Phase 3: Jira CSV Generation
- Adhere to Standards: Follow
docs/JIRA_CSV_INSTRUCTIONS.mdstrictly. - Map Fields:
Issue Type: Map phases toFeature(user-facing) orTask(internal).Summary: 10-15 word sentence case summary.Description: Must include both non-technical and technical layers.Priority: Set based on impact (default:Medium).Labels: Add relevant domain/surface labels.
- Write File: Save to
.topia/features/<name>/jira-tickets.csv.
Phase 4: Leadership Briefing
- Generate Brief: Create
leadership-brief.mdin the feature folder. - Include:
- Executive Summary: 2-sentence value proposition.
- Timeline: Estimated phases.
- Risk Assessment: Summary of findings from
adversary. - Proof of Quality: Mention planned test coverage.
Constraints
- Strict CSV Format: The Jira CSV must NOT have markdown around it when emitted as a file.
- Stakeholder Language: Descriptions in the "Overview" section must be devoid of jargon.
- No Code: This skill generates documentation and metadata only; it does not implement features.
- Consistency: Summary in CSV must match the intent of the corresponding phase in the plan.
Done When
- Feature folder
.topia/features/<name>/contains:user-stories.mdjira-tickets.csv(RFC-4180 compliant)leadership-brief.md
- Total ticket count matches the number of implementation phases.
Sharp Edges
Known failure modes for this skill. Check these before declaring done.
| Failure Mode | Severity | Mitigation |
|---|---|---|
Generating tickets without requirements.md and plan.md present |
CRITICAL | Phase 1 MUST locate both inputs; if missing, abort and tell user to run topia:idea + topia:plan first |
| Jira CSV not RFC-4180 compliant (unescaped commas, quotes, newlines inside fields) | CRITICAL | Quote every field; escape embedded " as ""; verify with a CSV linter before declaring done |
| Markdown fences around the CSV file content | HIGH | Constraint 1 — the .csv file must be raw CSV, not wrapped in ```; only the preview shown to the user may be fenced |
| Phase count ≠ ticket count | HIGH | Done-When requires 1:1 mapping; missing or duplicate tickets break import |
| User stories that paraphrase code instead of stating user value | HIGH | Story format As a <role>, I want <action>, so that <value> — the value clause is mandatory and non-technical |
| Leadership brief contains technical jargon | MEDIUM | Constraint 2 — Overview/Executive Summary in stakeholder language; technical detail belongs in ticket Description, not the brief |
| Acceptance criteria copy-pasted from plan instead of restated for testers | MEDIUM | Each story's AC must be testable by a non-author; rewrite plan's HOW into GIVEN/WHEN/THEN |
Skipping adversary-report.md when it exists |
MEDIUM | Risk Assessment section in the brief loses signal if adversary findings are not summarized |
| Writing implementation code to satisfy a Jira field | HIGH | Constraint 3 — documentation only. If a field needs code-level detail, point to a file path, don't inline code |
| Stale tickets after plan revision | MEDIUM | If plan.md is regenerated, re-run documentation to keep ticket/phase parity |
Output Format
LEADERSHIP PACKAGE — <feature-name>
===================================
Feature folder: .topia/features/<name>/
Artifacts:
- user-stories.md — Agile stories with acceptance criteria
- jira-tickets.csv — RFC-4180 import file (N tickets)
- leadership-brief.md — Executive summary, timeline, risks
Ticket summary:
| Phase | Issue Type | Summary |
| ... | ... | ... |
Cost Profile
~1000-2000 tokens input, ~1000 tokens output. Sonnet for professional writing quality.
Source: linenoize/topia — distributed by TomeVault.