Tariff Guide Generator

Create comprehensive, professional-grade tariff and customs guide documents for any country or customs territory. Output both Markdown and self-contained HTML with modern tech-doc styling.

Input Handling

Determine what the user needs:

Country/territory specified -- User names a country or customs territory (e.g., "Japan", "ASEAN", "UK", "Australia"). Research and write the full guide.
Outline provided -- User provides a chapter outline. Use it as the structure and fill in with researched content.
Update existing guide -- User has an existing guide that needs updating. Research current developments and update the relevant sections.
Comparison guide -- User wants to compare two or more systems. Structure as a comparative document with side-by-side analysis.

If the user provides minimal context, ask:

Which country or customs territory?
Target audience? (e.g., U.S. importers entering this market, local compliance professionals, general trade audience)
Should it cross-reference existing guides? (e.g., "assume reader knows the U.S. system")
Output format? (default: both Markdown + self-contained HTML)

Research Phase

Before writing, gather comprehensive information. Launch parallel research agents covering these topic areas:

Research Area 1: Structure and Institutions

Governing legislation (customs act, tariff act, trade law)
Key agencies (customs authority, trade tribunal, trade policy body, tax authority)
Classification system (HS-based structure, national digits, how many digits)
Tariff schedule structure (rate columns, preferential treatments)
How to access the official tariff schedule (URLs, databases, tools)

Research Area 2: Rates, Valuation, and Origin

Valuation basis (FOB, CIF, or other -- this is a critical distinguishing feature)
MFN tariff profile (average rates, rate ranges by sector)
Free trade agreements (list all FTAs with partner names, years, codes)
Rules of origin (non-preferential, preferential, proof of origin mechanisms)
Preferential programs (GSP equivalents, developing country preferences)

Research Area 3: Additional Duties and Taxes

Anti-dumping and countervailing duty system (retrospective vs. prospective, current major measures)
Safeguard measures (any active safeguards, TRQs)
Special tariffs/surtaxes (retaliatory tariffs, national security tariffs, any equivalent to U.S. Section 301/232/IEEPA)
Sales tax / VAT / GST at the border (rate, how calculated, recoverable?)
Excise duties (alcohol, tobacco, fuel, luxury goods)
Any unique mechanisms (e.g., EU CBAM, entry price systems)

Research Area 4: Procedures and Compliance

Customs declaration system (electronic system name, process)
De minimis thresholds (duty-free, tax-free, e-commerce)
Duty relief programs (drawback, bonded warehouses, temporary importation, processing zones)
Trusted trader programs (AEO equivalent, mutual recognition)
Binding classification rulings (process, validity, searchable database?)
Penalties and enforcement (audit lookback period, penalty structure, voluntary disclosure, appeal process)

Research Quality Requirements

Use current data (specify the date in the guide)
Include specific rates, thresholds, legal references, regulation numbers
Include official website URLs and database links
Verify data against official government sources where possible
Note any upcoming changes (pending legislation, scheduled rate changes)

Document Structure

Read references/document-structure.md for the standard chapter framework.

Every guide follows this core structure, adapted to the specific system:

Required Sections

Executive Summary -- Structural comparison table vs. U.S. (or another reference system if specified). Highlight the 3-5 most consequential differences. This section tells the reader what makes this system unique.
System Overview -- Legislative foundation, key agencies with roles and website URLs, how the system is organized.
Classification -- How the tariff number works, digit breakdown diagram, national extensions, how to access the official schedule.
Tariff Rates and Treatments -- MFN rates, preferential rates, all FTA treatment codes, the "best rate" rule if applicable.
Customs Valuation -- FOB vs. CIF (critical distinction), transaction value method, additions/deductions, currency conversion.
Rules of Origin -- Non-preferential and preferential, key FTA rules of origin, proof of origin mechanisms.
Total Landed Cost Calculation -- The complete formula from customs value to total charges. Must include 3 worked examples with step-by-step calculations showing realistic products and amounts.
Additional Duties -- AD/CVD system, safeguards, surtaxes, retaliatory tariffs, any unique mechanisms. Include current major measures with rates.
Sales Tax / VAT / GST -- Tax at the border (if applicable), rates, recovery mechanism, interaction with duty calculation.
De Minimis -- Thresholds for duty-free, tax-free, and e-commerce. Compare with U.S. $800 threshold.
Duty Relief and Special Programs -- Drawback, bonded warehousing, temporary importation, processing zones, trusted trader programs.
Compliance and Enforcement -- Audit lookback period, penalties, voluntary disclosure, appeal process.
Key Resources -- All official URLs, legislation references, key guidance documents organized in tables.
Quick Reference Cheat Sheet -- Condensed formula, key thresholds table, current additional duties summary, comparison table with other systems.
Disclaimers -- Not legal advice, rates change frequently, verify against official sources.

Required Elements

Every guide must include:

Structural comparison table (this system vs. U.S. and/or other systems)
Tariff number anatomy diagram (showing digit breakdown with labels)
Complete landed cost formula (step-by-step, showing all layers)
3 worked examples with realistic products, tariff codes, and amounts:
- Example 1: A duty-free or low-duty product (to show base case)
- Example 2: A product with moderate duty (to show standard calculation)
- Example 3: A product with additional duties/surtaxes (to show worst case)
Key thresholds table (de minimis, registration thresholds, etc.)
FTA/preferential treatment code table (all codes with partners and years)
Official resource URLs table
Key legislation reference table

Cross-References

When the audience has read a companion guide (e.g., the U.S. guide), use callout boxes to highlight differences:

"Key difference from U.S." callouts for structural differences
"Comparison with U.S." callouts for procedural similarities/differences
Do NOT re-explain foundational concepts (HS basics, GRI rules, WTO Valuation Agreement) -- reference the companion guide

Writing Style

Tone

Authoritative but accessible -- Write for professionals, not academics
Framework-focused -- Teach how to look things up, not snapshot current rates (rates change; the framework is durable)
Practical -- Include worked examples, decision trees, and step-by-step processes
Comparative -- Constantly relate back to the reader's known system

Formatting

Use markdown headers for hierarchy (## for chapters, ### for sections,
for subsections)
Use tables for structured data (rates, codes, comparisons)
Use blockquotes (>) for key differences and comparisons
Use code blocks for formulas, tariff number diagrams, and URLs
Use bold for key terms on first use
Keep paragraphs focused -- one concept per paragraph
Target 8,000-15,000 words depending on system complexity

HTML Generation

Read references/html-template.md for the complete CSS design system and HTML template.

After writing the Markdown version, create a self-contained HTML version with:

Design System

System font stack (no external font dependencies)
Color palette: Slate-900 text, blue-500 accents, slate-50 backgrounds
Sticky sidebar TOC (280px, fixed left, scrollable)
Content area (800px max-width, left margin for sidebar)
4 callout types: Info (blue), Warning (amber), Tip (green), Important (red)
Dark code blocks (slate-800 background)
Styled tables (dark header, alternating rows, hover highlight)
Formula boxes (dark gradient background, monospace font)
Worked example boxes (dark header, body, result footer with red amount)
Tariff anatomy diagrams (monospace, bordered box)
Badge/chips (for status indicators: Active, Suspended, Repealed)
Print stylesheet (hide sidebar, B&W-friendly, page breaks before h2)
Responsive (hide sidebar below 1024px)

HTML Requirements

Fully self-contained -- all CSS embedded in <style>, no external dependencies of any kind
All internal anchor links must resolve -- every href="#id" must have a corresponding id="..." element
Print-ready -- must look professional when printed to PDF
No JavaScript -- pure HTML + CSS

Verification

After generating both files, verify:

File sizes -- MD should be 30-80KB, HTML should be 40-100KB
Anchor links -- Extract all href="#..." and id="..." from HTML; confirm every href has a matching id
External dependencies -- Confirm zero <link>, <script src>, or external url() references in HTML
Content completeness -- Confirm all required sections are present
Worked examples -- Confirm 3 examples with correct arithmetic

Output

Deliver two files in a dedicated directory:

{country}-tariff/
├── {country}-tariff-guide.md
└── {country}-tariff-guide.html

Both files should contain identical content -- the HTML is a styled rendering of the Markdown.

Guidelines

Research thoroughly before writing. Launch parallel research agents to gather comprehensive data on all topic areas simultaneously.
Be specific. Include actual tariff codes, regulation numbers, SOR/CFR references, and official URLs.
Verify arithmetic in worked examples. Show each step so the reader can follow and verify independently.
Use consistent terminology. Define terms on first use and use them consistently throughout.
Date the document. Include the version date prominently and note that information reflects conditions as of that date.
When uncertain about a current rate or status, state what was known and direct the reader to the official source for verification.
Do not speculate about future policy. State current facts and pending legislation separately.
Keep the HTML visually consistent with companion guides if they exist. Reuse the same CSS design system for a cohesive collection.

tariff-guide