mt-freelance-intake.md541 lines22.9 KB
v1Orchestrator
| 1 | --- |
| 2 | name: mt-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their Malta tax returns AND mentions freelancing, self-employment, contracting, sole proprietorship, or self-occupied status. Trigger on phrases like "help me do my taxes", "prepare my TA24", "I'm self-employed in Malta", "I'm a freelancer in Malta", "do my taxes as a contractor", "prepare my VAT return and income tax", or any similar phrasing where the user is a Malta-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Malta self-employed tax workflow -- every other skill in the stack (malta-vat-return, malta-income-tax, malta-ssc, mt-estimated-tax, mt-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Malta full-year residents only; self-employed individuals and sole proprietors. |
| 4 | version: 0.1 |
| 5 | --- |
| 6 | |
| 7 | # Malta Self-Employed Intake Skill v0.1 |
| 8 | |
| 9 | ## What this file is |
| 10 | |
| 11 | The intake orchestrator for Malta-resident self-employed individuals. Every downstream Malta content skill (malta-vat-return, malta-income-tax, malta-ssc, mt-estimated-tax) and the assembly orchestrator (mt-return-assembly) depend on this skill running first to produce a structured intake package. |
| 12 | |
| 13 | This skill does not compute any tax figures. Its job is to collect all the facts, parse all the documents, confirm everything with the user, and hand off a clean intake package to `mt-return-assembly`. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Design principles |
| 18 | |
| 19 | v0.1 follows the same upload-first, inference-then-confirm pattern as us-ca-freelance-intake v0.2: |
| 20 | |
| 21 | 1. **Compact refusal sweep** using `ask_user_input_v0` -- 3 interactive questions, ~30 seconds. |
| 22 | 2. **Upload-first workflow** -- after the refusal check, the user dumps everything they have. |
| 23 | 3. **Inference pass** -- Claude parses every document and extracts as much as possible. |
| 24 | 4. **Gap-filling only** -- Claude asks the user ONLY about what is missing, ambiguous, or needs confirmation. |
| 25 | 5. **Single confirmation pass** at the end -- show the full picture, let the user correct anything wrong, hand off to downstream skills. |
| 26 | |
| 27 | Target: intake completes in 5 minutes for a prepared user, 15 minutes for a user who has to go fetch documents. |
| 28 | |
| 29 | ## Critical operating principles |
| 30 | |
| 31 | **Do not narrate the workflow.** Do not say "Phase 1," "Phase 2," "Now I'll ask you about deductions." Just do the work. |
| 32 | |
| 33 | **Do not ask questions that have already been answered.** If the refusal check established the user is Article 10 registered, do not later ask about VAT registration type. Track what is known. |
| 34 | |
| 35 | **Do not ask about things visible in uploaded documents.** If the bank statement shows quarterly SSC payments to DSS, do not ask "did you pay SSC." Confirm what you see, do not re-ask. |
| 36 | |
| 37 | **Use `ask_user_input_v0` for any multiple-choice question.** Text input is only for genuinely open-ended data (names, addresses, specific amounts when they cannot be inferred). |
| 38 | |
| 39 | **Prefer batching.** Ask 3 related questions in a single message when they do not depend on each other's answers. |
| 40 | |
| 41 | **Be terse but complete.** No hedging, no "let me know if you have questions," no "I hope this helps." |
| 42 | |
| 43 | **Exception for blocking decisions.** If a single question determines whether the user is in-scope or out-of-scope, ask it standalone. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Section 1 -- The opening |
| 48 | |
| 49 | When triggered, respond with ONE message that: |
| 50 | |
| 51 | 1. One-line greeting (no paragraph of expectation-setting) |
| 52 | 2. One-line summary of the flow (scope check -> upload -> gaps -> handoff to return assembly) |
| 53 | 3. One-line reviewer reminder (must be reviewed by warranted accountant before filing) |
| 54 | 4. Launch the refusal sweep immediately using `ask_user_input_v0` |
| 55 | |
| 56 | **Example first message:** |
| 57 | |
| 58 | > Let's get your 2025 Malta returns ready. Quick scope check, then you upload your documents, then I fill in the gaps. Target time: 10 minutes. |
| 59 | > |
| 60 | > Reminder: everything I produce needs to be reviewed and signed off by a warranted accountant before you file anything with CFR or DSS. I'm not a substitute for review. |
| 61 | > |
| 62 | > Scope check: |
| 63 | |
| 64 | Then immediately call `ask_user_input_v0` with the refusal questions. |
| 65 | |
| 66 | **Do NOT:** |
| 67 | - Write a welcome paragraph |
| 68 | - Explain the phases |
| 69 | - Ask "are you ready to start" |
| 70 | - List what documents you will eventually need |
| 71 | - Give a disclaimer beyond the one reviewer line |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## Section 2 -- Refusal sweep (compact) |
| 76 | |
| 77 | Present the refusal sweep as a single `ask_user_input_v0` call with 3 questions, all single-select. |
| 78 | |
| 79 | **The 3 questions to ask first:** |
| 80 | |
| 81 | ``` |
| 82 | Q1: "Malta residency in 2025?" |
| 83 | Options: ["Full year", "Part year", "Did not live in Malta"] |
| 84 | |
| 85 | Q2: "Business structure?" |
| 86 | Options: ["Sole proprietor / self-occupied", "Partnership", "Limited company (Ltd)", "Not sure"] |
| 87 | |
| 88 | Q3: "Employment status in 2025?" |
| 89 | Options: ["Fully self-employed (no employer)", "Employed + side self-employment (TA22 eligible)", "Employed only (no self-employment income)"] |
| 90 | ``` |
| 91 | |
| 92 | **After the response, evaluate:** |
| 93 | |
| 94 | - **Q1 = Full year** -> continue |
| 95 | - **Q1 = Part year or did not live in Malta** -> stop. "I'm set up for full-year Malta residents only. Part-year or non-residents have different rules around source and remittance basis. You need a warranted accountant who handles non-resident returns." |
| 96 | |
| 97 | - **Q2 = Sole proprietor / self-occupied** -> continue |
| 98 | - **Q2 = Partnership** -> stop. "Partnerships file separately and have different reporting requirements. You need a warranted accountant familiar with partnership returns." |
| 99 | - **Q2 = Limited company (Ltd)** -> stop. "I don't cover corporate returns. Limited companies file CT returns with separate rules. You need a warranted accountant." |
| 100 | - **Q2 = Not sure** -> ask one follow-up: "Do you invoice clients in your own name (or a trade name), or do you have a registered company with the MFSA? If you invoice in your own name, you're a sole proprietor. If you have a registered Ltd, you're a limited company." |
| 101 | |
| 102 | - **Q3 = Fully self-employed** -> continue (TA24 path, Class 2 SSC) |
| 103 | - **Q3 = Employed + side self-employment** -> continue with a flag: possible TA22 regime if net profit under EUR 12,000. Will evaluate after inference. |
| 104 | - **Q3 = Employed only** -> stop. "You don't have self-employment income. This workflow is for self-employed individuals. Your employer handles your tax through FSS deductions. If you have other income (rental, investments), you need a warranted accountant for your TA form." |
| 105 | |
| 106 | **After Q1-Q3 pass, ask the second batch of scope questions (also batched):** |
| 107 | |
| 108 | ``` |
| 109 | Q4: "VAT registration type?" |
| 110 | Options: ["Article 10 (standard VAT registration)", "Article 11 (small enterprise exemption)", "Not VAT registered", "Not sure"] |
| 111 | |
| 112 | Q5: "Marital status?" |
| 113 | Options: ["Single", "Married", "Single parent"] |
| 114 | |
| 115 | Q6: "Industry?" |
| 116 | Options: ["Software / tech / IT services", "Professional services (accounting, legal, consulting)", "Trades (construction, electrical, plumbing)", "Creative (design, media, photography)", "Other"] |
| 117 | ``` |
| 118 | |
| 119 | **Evaluate Q4:** |
| 120 | - **Article 10** -> continue. Standard VAT3 quarterly returns. |
| 121 | - **Article 11** -> continue. Annual declaration, no input VAT recovery, turnover must be under EUR 35,000. |
| 122 | - **Not VAT registered** -> continue with a flag: if turnover exceeds EUR 35,000, registration is mandatory. Will check after inference. |
| 123 | - **Not sure** -> ask one follow-up: "Do you charge 18% VAT on your invoices? If yes, you're Article 10. If your invoices say 'exempt under Article 11' or show no VAT, you're Article 11 or unregistered." |
| 124 | |
| 125 | **Evaluate Q5:** |
| 126 | - All options -> note for rate table selection. Continue. |
| 127 | |
| 128 | **Evaluate Q6:** |
| 129 | - All options -> note for expense classification context. Continue. |
| 130 | |
| 131 | **Total time:** ~45 seconds if the user taps through. |
| 132 | |
| 133 | --- |
| 134 | |
| 135 | ## Section 3 -- The dump |
| 136 | |
| 137 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 138 | |
| 139 | **Example:** |
| 140 | |
| 141 | > Scope is good. Now upload everything you have for 2025 -- drop it all in at once: |
| 142 | > |
| 143 | > - Business bank statement(s) for all of 2025 (CSV or PDF) |
| 144 | > - Sales invoices issued in 2025 |
| 145 | > - Purchase invoices / receipts for business expenses |
| 146 | > - Prior year TA24 return (or at least last year's final tax liability) |
| 147 | > - Prior VAT3 returns for 2025 (if Article 10) |
| 148 | > - SSC payment receipts or DSS statements |
| 149 | > - Any MTCA notices or correspondence |
| 150 | > - Capital asset purchase receipts (computers, equipment, vehicles) |
| 151 | > - Anything else tax-related you have |
| 152 | > |
| 153 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 154 | |
| 155 | Then wait. Do not ask any other questions while waiting. |
| 156 | |
| 157 | **If the user uploads a partial dump and says "that's what I have":** move to inference. Do not demand more. Request specific missing items during gap-filling. |
| 158 | |
| 159 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 160 | > Check these places: |
| 161 | > - Business bank: download 2025 statements as PDF or CSV |
| 162 | > - Email: search for "invoice", "VAT", "TA24", "MTCA", "DSS" |
| 163 | > - MTCA e-Services portal: download prior returns |
| 164 | > - Your accountant from last year, if you had one |
| 165 | > - Dropbox / Google Drive for saved invoices |
| 166 | > |
| 167 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## Section 4 -- The inference pass |
| 172 | |
| 173 | When documents arrive, parse each one. For each document, extract: |
| 174 | |
| 175 | **Bank statement:** |
| 176 | - Total deposits (candidate gross receipts) |
| 177 | - Recurring inflows (client payments with names) |
| 178 | - Outflows to Inland Revenue / CFR (provisional tax payments with dates) |
| 179 | - Outflows to DSS (SSC payments with dates and amounts) |
| 180 | - Outflows to CFR VAT account (VAT payments with dates) |
| 181 | - Outflows to suppliers (business expenses by category) |
| 182 | - Equipment purchases (potential capital items) |
| 183 | - Transfers to personal account (owner draws) |
| 184 | - Any rent payments (potential home office or business premises) |
| 185 | - SaaS / software subscriptions |
| 186 | - Professional memberships (MIA, ACCA, etc.) |
| 187 | - Insurance payments (PI, motor, etc.) |
| 188 | |
| 189 | **Sales invoices:** |
| 190 | - Client names and amounts |
| 191 | - Whether VAT was charged (Article 10 indicator) |
| 192 | - Whether invoices say "exempt" or show no VAT (Article 11 indicator) |
| 193 | - Total turnover reconciliation against bank deposits |
| 194 | - Any foreign clients (EU or non-EU -- reverse charge implications) |
| 195 | |
| 196 | **Purchase invoices / receipts:** |
| 197 | - Expense category (overhead, capital, resale) |
| 198 | - VAT amount on each (reclaimable for Article 10, cost for Article 11) |
| 199 | - Supplier location (local, EU, non-EU) |
| 200 | - Any items over EUR 1,160 gross (VAT capital goods threshold) |
| 201 | - Any blocked categories (entertainment, personal) |
| 202 | |
| 203 | **Prior year TA24:** |
| 204 | - Prior year final tax liability (drives provisional tax calculation) |
| 205 | - Prior year net income (drives SSC calculation) |
| 206 | - Prior year capital allowances schedule (continuing depreciation) |
| 207 | - Filing status and rate table used |
| 208 | |
| 209 | **Prior VAT3 returns:** |
| 210 | - Quarterly turnover and VAT collected |
| 211 | - Input VAT claimed |
| 212 | - Any excess credit carried forward |
| 213 | - Box structure consistency |
| 214 | |
| 215 | **SSC statements / DSS receipts:** |
| 216 | - Quarterly SSC payments made in 2025 |
| 217 | - Category (SA minimum, SB rate, SC maximum) |
| 218 | - Any arrears |
| 219 | |
| 220 | **After parsing everything, build an internal inference object.** Do not show the raw inference yet -- transform it into a compact summary for the user in Section 5. |
| 221 | |
| 222 | --- |
| 223 | |
| 224 | ## Section 5 -- The confirmation |
| 225 | |
| 226 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 227 | |
| 228 | **Example summary message:** |
| 229 | |
| 230 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 231 | > |
| 232 | > **Identity** |
| 233 | > - Joe Borg, single |
| 234 | > - Full-year Malta resident (Birkirkara) |
| 235 | > - Self-occupied, sole proprietor |
| 236 | > - VAT: Article 10 (MT 1234-5678) |
| 237 | > |
| 238 | > **Income (from bank statement + invoices)** |
| 239 | > - Gross receipts (ex-VAT): ~EUR 52,000 |
| 240 | > - XYZ Tech Ltd: EUR 24,000 (monthly retainer) |
| 241 | > - ABC Consulting: EUR 18,000 (project work) |
| 242 | > - Various smaller clients: EUR 10,000 |
| 243 | > - VAT collected (18%): ~EUR 9,360 |
| 244 | > |
| 245 | > **Expenses (from bank statement + purchase invoices)** |
| 246 | > - Office rent: EUR 3,600 |
| 247 | > - Software / SaaS: EUR 1,800 |
| 248 | > - Professional insurance: EUR 450 |
| 249 | > - Accountancy fees: EUR 900 |
| 250 | > - Phone / internet: EUR 720 (TBD -- need business use %) |
| 251 | > - Motor vehicle: EUR 2,400 fuel + EUR 600 maintenance (TBD -- need business use %) |
| 252 | > - Equipment: MacBook Pro EUR 2,100 (March 2025) -- capital item, 25% depreciation |
| 253 | > - Input VAT on purchases: ~EUR 1,850 (reclaimable, Article 10) |
| 254 | > |
| 255 | > **SSC (from DSS statements)** |
| 256 | > - Class 2 quarterly payments: EUR 470.34 x 4 = EUR 1,881.36 (SA minimum) |
| 257 | > - Born 1990 -- post-1962 cap applies if income rises |
| 258 | > |
| 259 | > **Provisional tax (from bank statement)** |
| 260 | > - 1st instalment 30 Apr: EUR 800 |
| 261 | > - 2nd instalment 31 Aug: EUR 1,200 |
| 262 | > - 3rd instalment 21 Dec: EUR 2,000 |
| 263 | > - Total paid: EUR 4,000 |
| 264 | > |
| 265 | > **Prior year (from 2024 TA24)** |
| 266 | > - 2024 final tax liability: EUR 4,200 |
| 267 | > - 2024 net self-employment income: EUR 28,000 |
| 268 | > - Expected 2025 provisional tax (based on 2024): EUR 4,200 -- matches payments |
| 269 | > |
| 270 | > **VAT (from prior VAT3 returns)** |
| 271 | > - Q1-Q3 2025 filed, Q4 outstanding |
| 272 | > - Excess credit b/f from Q4 2024: EUR 120 |
| 273 | > |
| 274 | > **Flags I already see:** |
| 275 | > 1. Phone / internet -- need business use percentage (T2 item) |
| 276 | > 2. Motor vehicle -- need business use percentage and mileage log (T2 item) |
| 277 | > 3. MacBook Pro EUR 2,100 -- capital item, goes to Box 15 not Box 2. Also exceeds EUR 1,160 VAT capital goods threshold (Box 30 on VAT3) |
| 278 | > 4. Q4 2025 VAT3 not yet filed -- will prepare as part of this workflow |
| 279 | > 5. If TA22 was flagged: net profit appears to exceed EUR 12,000, so TA22 flat rate is less favourable than expected |
| 280 | > |
| 281 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 282 | |
| 283 | --- |
| 284 | |
| 285 | ## Section 6 -- Gap filling |
| 286 | |
| 287 | After the user confirms the summary (or corrects it), ask about things that cannot be inferred from documents. Use `ask_user_input_v0` where possible. |
| 288 | |
| 289 | **Things that usually cannot be inferred:** |
| 290 | |
| 291 | 1. **Home office** -- Cannot tell from documents whether a dedicated workspace exists. |
| 292 | 2. **Private use percentage** -- Phone, internet, motor vehicle business-use split. |
| 293 | 3. **Capital allowances from prior years** -- Continuing depreciation on assets acquired before 2025 (unless prior TA24 has the schedule). |
| 294 | 4. **Exempt supplies** -- Whether any income is VAT-exempt (medical, educational, insurance, financial services). |
| 295 | 5. **Birth year** -- Needed for SSC maximum cap determination. |
| 296 | 6. **Other income** -- Employment income, rental, dividends, interest (Box 4 of TA24). |
| 297 | |
| 298 | **Home office gap-filling example:** |
| 299 | |
| 300 | Call `ask_user_input_v0` with: |
| 301 | |
| 302 | ``` |
| 303 | Q: "Home office?" |
| 304 | Options: [ |
| 305 | "Dedicated room, used ONLY for work", |
| 306 | "Dedicated corner/desk, used ONLY for work", |
| 307 | "Shared space (kitchen table, living room)", |
| 308 | "Separate business premises (not at home)", |
| 309 | "No fixed workspace" |
| 310 | ] |
| 311 | ``` |
| 312 | |
| 313 | If option 1 -> ask for room count (total rooms in home) or floor area percentage. |
| 314 | If option 2 -> flag as T2 for reviewer: dedicated corner may qualify but is less clear-cut than a full room. |
| 315 | If option 3 -> "A shared space does not qualify for a home office deduction under Article 14. I'll skip this deduction." |
| 316 | If option 4 -> rent is already captured in expenses. No home office calculation needed. |
| 317 | If option 5 -> skip home office entirely. |
| 318 | |
| 319 | **Private use percentage example:** |
| 320 | |
| 321 | Call `ask_user_input_v0` with: |
| 322 | |
| 323 | ``` |
| 324 | Q: "Motor vehicle -- business use?" |
| 325 | Options: [ |
| 326 | "90%+ business (mileage log available)", |
| 327 | "70-90% business", |
| 328 | "50-70% business", |
| 329 | "Under 50% business", |
| 330 | "No vehicle used for business" |
| 331 | ] |
| 332 | ``` |
| 333 | |
| 334 | For phone/internet, similar question. |
| 335 | |
| 336 | Flag all private-use percentages as T2 -- warranted accountant must confirm the percentage is reasonable and documented. |
| 337 | |
| 338 | **Birth year:** |
| 339 | |
| 340 | If not determinable from documents, ask as a text input: "What year were you born? (Needed for SSC maximum cap calculation.)" |
| 341 | |
| 342 | --- |
| 343 | |
| 344 | ## Section 7 -- The final handoff |
| 345 | |
| 346 | Once gap-filling is done, produce a final handoff message and hand off to `mt-return-assembly`. |
| 347 | |
| 348 | **Example handoff message:** |
| 349 | |
| 350 | > Intake complete. Here's what's going to the return assembly: |
| 351 | > |
| 352 | > Self-employed sole proprietor, single, Article 10 VAT, full-year Malta resident. Gross EUR 52,000, estimated net ~EUR 41,000 before capital allowances and SSC. |
| 353 | > |
| 354 | > I'm now going to run the full Malta return preparation. This covers: |
| 355 | > 1. VAT3 return (Q4 2025 or annual if Article 11) |
| 356 | > 2. TA24 income tax return (2025) |
| 357 | > 3. Class 2 SSC reconciliation |
| 358 | > 4. Provisional tax schedule for 2026 |
| 359 | > |
| 360 | > You'll get back: |
| 361 | > 1. An Excel working paper with all forms and live formulas |
| 362 | > 2. A reviewer brief with positions, citations, and flags for your accountant |
| 363 | > 3. A filing calendar with all upcoming deadlines |
| 364 | > |
| 365 | > Starting now. |
| 366 | |
| 367 | Then internally invoke `mt-return-assembly` with the structured intake package. |
| 368 | |
| 369 | --- |
| 370 | |
| 371 | ## Section 8 -- Structured intake package (internal format) |
| 372 | |
| 373 | The downstream skill (`mt-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 374 | |
| 375 | ```json |
| 376 | { |
| 377 | "jurisdiction": "MT", |
| 378 | "tax_year": 2025, |
| 379 | "taxpayer": { |
| 380 | "name": "", |
| 381 | "birth_year": 0, |
| 382 | "marital_status": "single | married | parent", |
| 383 | "residency": "full_year", |
| 384 | "vat_number": "", |
| 385 | "vat_registration_type": "article_10 | article_11 | unregistered", |
| 386 | "employment_status": "self_employed | employed_plus_side", |
| 387 | "industry": "", |
| 388 | "entity_type": "sole_proprietor" |
| 389 | }, |
| 390 | "income": { |
| 391 | "gross_receipts_ex_vat": 0, |
| 392 | "vat_collected": 0, |
| 393 | "other_income": 0, |
| 394 | "client_breakdown": [] |
| 395 | }, |
| 396 | "expenses": { |
| 397 | "fully_deductible": [], |
| 398 | "mixed_use": [], |
| 399 | "blocked": [], |
| 400 | "capital_items": [] |
| 401 | }, |
| 402 | "vat": { |
| 403 | "quarterly_returns_filed": [], |
| 404 | "excess_credit_bf": 0, |
| 405 | "input_vat_reclaimable": 0, |
| 406 | "exempt_supplies": false, |
| 407 | "exempt_supply_details": "" |
| 408 | }, |
| 409 | "ssc": { |
| 410 | "birth_year": 0, |
| 411 | "class2_payments": [], |
| 412 | "total_paid": 0, |
| 413 | "category": "SA | SB | SC" |
| 414 | }, |
| 415 | "provisional_tax": { |
| 416 | "prior_year_liability": 0, |
| 417 | "payments_made": [], |
| 418 | "total_paid": 0 |
| 419 | }, |
| 420 | "prior_year": { |
| 421 | "final_tax_liability": 0, |
| 422 | "net_self_employment_income": 0, |
| 423 | "capital_allowances_schedule": [] |
| 424 | }, |
| 425 | "home_office": { |
| 426 | "qualifies": false, |
| 427 | "percentage": 0, |
| 428 | "method": "rooms | floor_area" |
| 429 | }, |
| 430 | "private_use": { |
| 431 | "motor_vehicle_business_pct": 0, |
| 432 | "phone_business_pct": 0, |
| 433 | "internet_business_pct": 0 |
| 434 | }, |
| 435 | "open_flags": [], |
| 436 | "refusals_triggered": [], |
| 437 | "documents_received": [] |
| 438 | } |
| 439 | ``` |
| 440 | |
| 441 | --- |
| 442 | |
| 443 | ## Section 9 -- Refusal handling |
| 444 | |
| 445 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., partnership structure discovered in documents). |
| 446 | |
| 447 | When a refusal fires: |
| 448 | 1. Stop the workflow |
| 449 | 2. State the specific reason in one sentence |
| 450 | 3. Recommend the path forward (specific practitioner type) |
| 451 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 452 | |
| 453 | **Do not:** |
| 454 | - Apologize profusely |
| 455 | - Try to work around the refusal |
| 456 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 457 | - Continue silently |
| 458 | |
| 459 | **Sample refusal:** |
| 460 | |
| 461 | > Stop -- you have a registered limited company. I'm set up for sole proprietors and self-occupied individuals only. Limited companies file CT returns with different rules for directors' remuneration, dividends, and corporate tax. You need a warranted accountant familiar with Ltd company returns. |
| 462 | > |
| 463 | > I can't help with this one. |
| 464 | |
| 465 | --- |
| 466 | |
| 467 | ## Section 10 -- Self-checks |
| 468 | |
| 469 | **Check IN1 -- No one-question-at-a-time prose in the refusal sweep.** If the skill asked "Question 1 of 10" or walked through questions as separate messages, check fails. |
| 470 | |
| 471 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 472 | |
| 473 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 474 | |
| 475 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 476 | |
| 477 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "did you pay SSC" after the bank statement showed DSS payments, check fails. |
| 478 | |
| 479 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 480 | |
| 481 | **Check IN7 -- Handoff to `mt-return-assembly` is explicit.** The user was told "I'm now going to run the return preparation," and the downstream orchestrator was explicitly invoked with the intake package. |
| 482 | |
| 483 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned reviewer signoff. |
| 484 | |
| 485 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 486 | |
| 487 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 488 | |
| 489 | **Check IN11 -- Total user-facing turn count is low.** Target: 8 turns or fewer from start to handoff for a prepared user (1 refusal batch + 1 upload + 1 confirmation + 1-3 gap fills + 1 handoff). More than 12 turns for a normal intake is a check failure. |
| 490 | |
| 491 | **Check IN12 -- VAT registration type was established.** Article 10 vs Article 11 was confirmed before inference, as it changes how every transaction is classified. |
| 492 | |
| 493 | --- |
| 494 | |
| 495 | ## Section 11 -- Performance targets |
| 496 | |
| 497 | For a prepared user (documents in a folder, ready to upload): |
| 498 | - **Refusal sweep**: 45 seconds (1-2 interactive turns) |
| 499 | - **Document upload**: 2 minutes (1 upload turn) |
| 500 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 501 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 502 | - **Handoff**: immediate |
| 503 | - **Total**: ~6 minutes |
| 504 | |
| 505 | For an unprepared user (has to go fetch documents): |
| 506 | - Refusal sweep: same |
| 507 | - Document discovery: 10-20 minutes offline |
| 508 | - Rest: same |
| 509 | - **Total**: 15-25 minutes |
| 510 | |
| 511 | --- |
| 512 | |
| 513 | ## Section 12 -- Cross-skill references |
| 514 | |
| 515 | **Inputs:** User-provided documents and answers. |
| 516 | |
| 517 | **Outputs:** Structured intake package consumed by `mt-return-assembly`. |
| 518 | |
| 519 | **Downstream skills triggered (via mt-return-assembly):** |
| 520 | - `malta-vat-return` -- VAT3 quarterly or Article 11 annual declaration |
| 521 | - `malta-income-tax` -- TA24 self-employed return |
| 522 | - `malta-ssc` -- Class 2 social security contributions |
| 523 | - `mt-estimated-tax` -- Provisional tax schedule |
| 524 | |
| 525 | --- |
| 526 | |
| 527 | ### Change log |
| 528 | |
| 529 | - **v0.1 (April 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on us-ca-freelance-intake v0.2. |
| 530 | |
| 531 | ## End of Intake Skill v0.1 |
| 532 | |
| 533 | |
| 534 | --- |
| 535 | |
| 536 | ## Disclaimer |
| 537 | |
| 538 | This skill and its outputs are provided for informational and computational purposes only and do not constitute tax, legal, or financial advice. Open Accountants and its contributors accept no liability for any errors, omissions, or outcomes arising from the use of this skill. All outputs must be reviewed and signed off by a qualified professional (such as a CPA, EA, tax attorney, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 539 | |
| 540 | The most up-to-date, verified version of this skill is maintained at [openaccountants.com](https://openaccountants.com). Log in to access the latest version, request a professional review from a licensed accountant, and track updates as tax law changes. |
| 541 |
Run this skill, then get an accountant to check it
After running the full skill pack in Claude, sign up and upload your worksheet. We'll connect you with a trusted accountant in our network who can review your numbers before you file.
Depends on
Quality
Q2: Research-verified
Deep research against tax authority sources. Not yet tested on real data.
Needs real client data + practitioner sign-off to reach Q1.
Accountant Review
Unverified
0/19
About
ALWAYS USE THIS SKILL when a user asks for help preparing their Malta tax returns AND mentions freelancing, self-employment, contracting, sole proprietorship, or self-occupied status. Trigger on phrases like "help me do my taxes", "prepare my TA24", "I'm self-employed in Malta", "I'm a freelancer in Malta", "do my taxes as a contractor", "prepare my VAT return and income tax", or any similar phrasing where the user is a Malta-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the Malta self-employed tax workflow -- every other skill in the stack (malta-vat-return, malta-income-tax, malta-ssc, mt-estimated-tax, mt-return-assembly) depends on this skill running first to produce a structured intake package. Uses upload-first workflow -- the user dumps all their documents and the skill infers as much as possible before asking questions. Uses ask_user_input_v0 for structured questions instead of one-at-a-time prose. Built for speed. Malta full-year residents only; self-employed individuals and sole proprietors.
MTty-2025