travel-plan-spreadsheet-generator

travel-plan-spreadsheet-generator

Turn messy travel inputs into a calm, editable .xlsx workbook with deterministic structure and pragmatic trip-planning judgment.

Decision Tree

What did the user actually ask for?

• The user wants an editable workbook, spreadsheet, tracker, or .xlsx Use this skill.

• The user gave PDFs, screenshots, notes, bookings, shopping asks, or conference constraints Extract everything you can first. Do not ask questions that the attachments already answer.

• The request is missing material facts that would make the workbook wrong Consolidate known blockers into a short intake batch. Follow up if materially new safety or correctness issues emerge; do not reinterview answered context. Read references/intake-protocol.md.

• The request has non-blocking ambiguity Proceed with explicit assumptions and visible review flags. Do not stop the build just to perfect every detail.

• The user only wants prose, lightweight recommendations, or a casual itinerary chat Do not use this skill as the primary tool.

• The harness offers a spreadsheet skill or equivalent local guidance Discover and load it through the harness before spreadsheet work, then apply this skill's workbook-specific contract. Do not assume a machine-specific installation path.

Quick Reference

Need	Read or run	Why
Consolidated intake and material follow-ups	references/intake-protocol.md	Avoid both repeated questioning and unsafe guesses
Deterministic workbook contract	references/workbook-spec.md	Sheet order, widths, merges, formulas, palette
Canonical trip model fields	references/trip-model.md	Build the internal model before writing cells
Field-to-sheet mapping	references/mapping-rules.md	Keep Pack vs Buy vs Prep clean
Volatile travel research rules	references/research-policy.md	Verify visas, transit, medicine, conference dates, and other unstable facts
Build the workbook	python3 scripts/build_workbook.py --trip-model /path/to/model.json	Generate the .xlsx artifact
Validate the workbook	python3 scripts/validate_workbook.py /path/to/output.xlsx --trip-model /path/to/model.json	Check structure, formulas, validations, and row patterns
Visual-risk scan	python3 scripts/render_check.py /path/to/output.xlsx	Catch likely clipping or spillover when a renderer is unavailable
Review packaging and sample build	python3 scripts/test_skill.py /path/to/skill	Run the local functional smoke test

Operating Rules

1. Start with extraction, not interrogation. Read the user's PDFs, screenshots, pasted notes, flight details, hotel confirmations, shopping asks, and fixed commitments before asking anything.
2. Separate blockers from non-blockers. Consolidate known missing essentials, then follow up only for materially new safety or correctness issues. Never guess a critical fact to meet a question limit or re-ask answered questions.
3. Build a canonical trip model before touching the workbook. Use templates/trip_model_schema.json and references/trip-model.md.
4. Keep the deterministic and heuristic layers separate:
   • Use scripts/build_workbook.py for filename strategy, sheet order, merges, widths, formulas, validations, fills, fonts, borders, and fixed row patterns.
   • Use judgment for extracting messy facts, reconciling contradictions, deciding pace, keeping shopping visible, pruning absurd plans, and deciding when split plans are required.
5. Default to the whole group staying together unless the evidence clearly says otherwise. When only part of the group is booked, create split fallbacks and visible review flags instead of pretending coverage exists.
6. Keep shopping visible across the workbook. It belongs in Daily Plan, the destination options bank, and Buy List when relevant.
7. Research only what matters for this trip. Verify future or current entry rules, transit constraints, medicine rules, airline check-in windows, and event dates from official sources when they materially affect the plan.
8. Do not silently flatten contradictions. A mismatch between traveller count and booking coverage must surface in Overview, Bookings, Prep & Compliance, and the Daily Plan when it changes the day's shape.
9. Treat the workbook as the deliverable. After building it, run scripts/validate_workbook.py. If a renderer such as @oai/artifact-tool is available, do a visual pass before hand-off.

Intake Protocol

Ask nothing if the message and attachments already cover the essentials.

If a clarification batch is necessary, keep it short. These optional groupings may help; rename them or omit empty groups:

Required to proceed
- ...

Useful but optional
- ...

Documents or screenshots that would improve accuracy
- ...

Cover these only when relevant and still missing: trip name or destination, start/end dates, departure and final home arrival, cities or bases, traveller list and roles, passport nationalities when immigration matters, flights and transit, accommodation, fixed bookings, conference or family commitments, budget sensitivity, pace, mobility constraints, dietary constraints, shopping goals and requesters, group split patterns, pre-departure and recovery-day preference, official prep tasks, and preferred output filename.

Read references/intake-protocol.md for the full checklist, blocker logic, and wording rules.

Build Workflow

1. Extract facts from the user's files and notes.
2. Consolidate known blockers into an intake batch if needed; revisit only materially new safety or correctness issues as evidence arrives.
3. Build the canonical trip model and record assumptions, sources, review flags, and shopping objectives explicitly.
4. Verify volatile facts that matter. Read references/research-policy.md.
5. Run scripts/build_workbook.py to generate the workbook.
6. Run scripts/validate_workbook.py on the generated .xlsx.
7. If @oai/artifact-tool or another renderer is available, render each sheet for a quick visual check. Otherwise run scripts/render_check.py for a structural visual-risk pass.
8. Hand over the workbook with a short summary of open flags, assumptions, and anything the user still needs to confirm.

Deterministic vs Heuristic Boundary

Deterministic builder responsibilities	Heuristic planner responsibilities
Workbook filename strategy	Extract facts from messy PDFs, screenshots, and notes
Sheet order and naming	Decide when contradictory evidence becomes a blocker
Merged ranges, widths, row heights, fills, borders, fonts	Reconcile conflicting traveller counts or date references
Column headers and validation lists	Choose realistic neighbourhood clusters and fallbacks
Formula generation and cross-sheet references	Protect conference or work anchors without wrecking the family plan
Status vocab and chip styling	Decide when split plans are necessary because coverage is partial
Source logging structure	Decide what belongs in Prep vs Pack vs Buy
One-day-before and one-day-after planner window	Prune absurd routes, overpacked days, or cross-city zig-zags

Do not improvise the deterministic layer in prose. Use the builder script.

If the requested workbook needs layout, styling, or features outside the supported builder contract, explain the limitation and choose a suitable alternative workflow or propose a scoped extension. Do not invent customization flags or claim the standard validator certifies a different workbook shape.

Sources and maintenance

Keep the trip model, dates, formulas, coverage flags, and builder/validator contract stable. Continue the required official-source checks for material volatile travel facts. When skill or runtime guidance is insufficient, stale, or conflicting, consult relevant official documentation or trusted primary sources rather than browsing routinely. Report unresolved limits and propose a sourced correction with a sample trip model or regression case. Edit the canonical skill only when maintenance is in scope, never silently update an installed copy.

Reading Guide

Task	Read
Exact workbook architecture, merges, counters, naming rules	references/workbook-spec.md
Intake questions, blockers, and material follow-ups	references/intake-protocol.md
Source verification, official-source priority, and what to research	references/research-policy.md
Canonical model fields and normalization rules	references/trip-model.md
Sheet-mapping and categorization rules	references/mapping-rules.md
Failure modes and anti-patterns	references/gotchas.md
Portability and spreadsheet-runtime notes	references/cross-harness-notes.md

Gotchas

1. Avoid drip-fed questions by extracting first and consolidating known blockers. New safety or correctness issues justify follow-up; non-blockers can use explicit assumptions and review flags.
2. Do not bury shopping in a note field. If shopping matters, surface it in Daily Plan, the options bank, and Buy List.
3. Do not turn Pack List into Buy List. Pack is what physically travels. Buy is the purchase tracker.
4. Do not silently accept partial coverage. When flights, hotel rooms, or attraction tickets cover fewer people than the plan assumes, keep the mismatch visible.
5. Do not over-research. Only add prep or compliance tasks that actually matter for this route, these passports, these medicines, and these commitments.

Helper Files

• scripts/build_workbook.py builds the workbook from a canonical model.
• scripts/validate_workbook.py checks structure, formulas, data validations, widths, merges, and Daily Plan row patterns.
• scripts/render_check.py performs a lightweight visual-risk scan when a richer renderer is unavailable.
• templates/trip_model_schema.json defines the canonical trip-model contract.
• templates/workbook_template_spec.yaml mirrors the deterministic layout contract for human review.