uk-freelance-intake.md593 lines25.0 KB
v1Orchestrator
| 1 | --- |
| 2 | name: uk-freelance-intake |
| 3 | description: ALWAYS USE THIS SKILL when a user asks for help preparing their UK tax returns AND mentions freelancing, self-employment, sole trading, contracting, or side hustle income. Trigger on phrases like "help me do my UK taxes", "prepare my self-assessment", "I'm self-employed in the UK", "I'm a sole trader", "do my SA100", "prepare my tax return", or any similar phrasing where the user is a UK-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the UK self-employed tax workflow -- every other skill in the stack (uk-vat-return, uk-self-employment-sa103, uk-income-tax-sa100, uk-national-insurance, uk-student-loan-repayment, uk-payments-on-account, uk-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. UK full-year residents only; sole traders. |
| 4 | version: 0.1 |
| 5 | --- |
| 6 | |
| 7 | # UK Self-Employed Intake Skill v0.1 |
| 8 | |
| 9 | ## What this file is |
| 10 | |
| 11 | The intake orchestrator for UK-resident sole traders. Every downstream UK content skill (uk-vat-return, uk-self-employment-sa103, uk-income-tax-sa100, uk-national-insurance, uk-student-loan-repayment, uk-payments-on-account) and the assembly orchestrator (uk-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 `uk-return-assembly`. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Design principles |
| 18 | |
| 19 | v0.1 follows the same upload-first, inference-then-confirm pattern as mt-freelance-intake v0.1: |
| 20 | |
| 21 | 1. **Compact refusal sweep** using `ask_user_input_v0` -- 3-4 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 VAT registered, do not later ask about VAT status. Track what is known. |
| 34 | |
| 35 | **Do not ask about things visible in uploaded documents.** If the bank statement shows quarterly VAT payments to HMRC, do not ask "are you VAT registered." 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 a chartered 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/26 UK 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 chartered accountant or licensed tax adviser before you file anything with HMRC. I'm not a substitute for professional 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 4 questions, all single-select. |
| 78 | |
| 79 | **The 4 questions to ask first:** |
| 80 | |
| 81 | ``` |
| 82 | Q1: "UK residency in 2025/26?" |
| 83 | Options: ["Full year UK resident", "Part year", "Non-resident"] |
| 84 | |
| 85 | Q2: "Business structure?" |
| 86 | Options: ["Sole trader (self-employed individual)", "Limited company (Ltd)", "LLP / Partnership", "Not sure"] |
| 87 | |
| 88 | Q3: "VAT registered?" |
| 89 | Options: ["Yes -- standard VAT registered", "Yes -- Flat Rate Scheme", "Not VAT registered (below GBP 90,000 threshold)", "Not sure"] |
| 90 | |
| 91 | Q4: "Employees?" |
| 92 | Options: ["No employees", "1-5 employees", "More than 5 employees"] |
| 93 | ``` |
| 94 | |
| 95 | **After the response, evaluate:** |
| 96 | |
| 97 | - **Q1 = Full year** -> continue |
| 98 | - **Q1 = Part year or Non-resident** -> stop. "I'm set up for full-year UK residents only. Part-year or non-residents have split-year treatment or different sourcing rules. You need a chartered accountant who handles non-resident returns." |
| 99 | |
| 100 | - **Q2 = Sole trader** -> continue |
| 101 | - **Q2 = Limited company (Ltd)** -> stop. "I don't cover corporate returns. Limited companies file CT600 returns with separate rules for directors' salaries and dividends. You need a chartered accountant." |
| 102 | - **Q2 = LLP / Partnership** -> stop. "Partnerships file SA800 partnership returns with profit-sharing arrangements. You need a chartered accountant familiar with partnership returns." |
| 103 | - **Q2 = Not sure** -> ask one follow-up: "Do you invoice clients in your own name and report income on your personal tax return? If so, you're a sole trader. If you have a company registered at Companies House, you're a Ltd. If you share profits with partners, you're in a partnership." |
| 104 | |
| 105 | - **Q3 = Yes -- standard** -> continue. Quarterly VAT returns. |
| 106 | - **Q3 = Yes -- Flat Rate Scheme** -> continue with a flag: FRS percentage needed for the trade sector. |
| 107 | - **Q3 = Not VAT registered** -> continue with a flag: if turnover exceeds GBP 90,000 in a rolling 12-month period, registration is mandatory. Will check after inference. |
| 108 | - **Q3 = Not sure** -> ask one follow-up: "Do you charge VAT on your invoices? If yes, you're VAT registered. If your invoices show no VAT, you're likely not registered." |
| 109 | |
| 110 | - **Q4 = No employees** -> continue |
| 111 | - **Q4 = 1-5** -> continue with a flag: PAYE obligations exist but are out of scope. Flag for chartered accountant review. |
| 112 | - **Q4 = More than 5** -> stop. "I'm set up for sole operators. With more than 5 employees, the PAYE and employment law complexity requires a dedicated chartered accountant." |
| 113 | |
| 114 | **Total time:** ~30 seconds if the user taps through. |
| 115 | |
| 116 | --- |
| 117 | |
| 118 | ## Section 3 -- The dump |
| 119 | |
| 120 | Once the refusal sweep passes, immediately ask for the document dump. Single message. No preamble. |
| 121 | |
| 122 | **Example:** |
| 123 | |
| 124 | > Scope is good. Now upload everything you have for 2025/26 (6 April 2025 to 5 April 2026) -- drop it all in at once: |
| 125 | > |
| 126 | > - Business bank statement(s) for the full tax year (CSV or PDF) |
| 127 | > - Sales invoices issued in 2025/26 |
| 128 | > - Purchase invoices / receipts for business expenses |
| 129 | > - Prior year SA302 (tax calculation) or SA100 return |
| 130 | > - P60 or payslips (if you also have employment income) |
| 131 | > - Student loan statement (if applicable) |
| 132 | > - VAT returns filed during 2025/26 (if VAT registered) |
| 133 | > - Any HMRC correspondence or payment statements |
| 134 | > - Capital asset purchase receipts (computers, equipment, vehicles) |
| 135 | > - Anything else tax-related you have |
| 136 | > |
| 137 | > Don't worry about labeling or organizing -- I'll figure out what each file is. Drag and drop when ready. |
| 138 | |
| 139 | Then wait. Do not ask any other questions while waiting. |
| 140 | |
| 141 | **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. |
| 142 | |
| 143 | **If the user says "I don't know what I have":** Switch to guided mode: |
| 144 | > Check these places: |
| 145 | > - Business bank: download 2025/26 statements as PDF or CSV |
| 146 | > - Email: search for "invoice", "HMRC", "tax return", "P60", "student loan" |
| 147 | > - HMRC online account (gov.uk): download prior SA302, payment statements |
| 148 | > - Your accountant from last year, if you had one |
| 149 | > - Dropbox / Google Drive for saved invoices |
| 150 | > - Student Loans Company portal: download annual statement |
| 151 | > |
| 152 | > Come back when you have something to upload. I'll work with whatever you bring. |
| 153 | |
| 154 | --- |
| 155 | |
| 156 | ## Section 4 -- The inference pass |
| 157 | |
| 158 | When documents arrive, parse each one. For each document, extract: |
| 159 | |
| 160 | **Bank statement:** |
| 161 | - Total deposits (candidate gross turnover) |
| 162 | - Recurring inflows (client payments with names) |
| 163 | - Outflows to HMRC (Self Assessment payments with dates -- payments on account + balancing payment) |
| 164 | - Outflows to HMRC (VAT payments with dates) |
| 165 | - Outflows to suppliers (business expenses by category) |
| 166 | - Equipment purchases (potential capital allowances) |
| 167 | - Transfers to personal account (drawings) |
| 168 | - Any rent payments (business premises or potential use of home) |
| 169 | - SaaS / software subscriptions |
| 170 | - Professional memberships (ICAS, ICAEW, CIMA, etc.) |
| 171 | - Insurance payments (PI, motor, etc.) |
| 172 | - Telephone / broadband payments |
| 173 | - Motor vehicle expenses (fuel, maintenance, insurance) |
| 174 | |
| 175 | **Sales invoices:** |
| 176 | - Client names and amounts |
| 177 | - Whether VAT was charged (VAT registration indicator) |
| 178 | - Total turnover reconciliation against bank deposits |
| 179 | - Any non-UK clients (reverse charge / outside scope of UK VAT) |
| 180 | - CIS deductions shown (Construction Industry Scheme -- flag) |
| 181 | |
| 182 | **Purchase invoices / receipts:** |
| 183 | - Expense category (revenue, capital, disallowable) |
| 184 | - VAT amount on each (reclaimable if VAT registered) |
| 185 | - Any items qualifying for Annual Investment Allowance (AIA) |
| 186 | - Any disallowable categories (entertainment, non-business) |
| 187 | |
| 188 | **Prior year SA302 / SA100:** |
| 189 | - Prior year total tax liability (drives payments on account) |
| 190 | - Prior year net self-employment income |
| 191 | - Prior year capital allowances schedule |
| 192 | - Prior year payments on account made |
| 193 | - Any balancing payment or refund |
| 194 | |
| 195 | **P60 / payslips (if also employed):** |
| 196 | - Gross employment income |
| 197 | - Tax deducted via PAYE |
| 198 | - NIC deducted (Class 1) |
| 199 | - Tax code used |
| 200 | - Student loan deductions via PAYE |
| 201 | |
| 202 | **Student loan statement:** |
| 203 | - Plan type (Plan 1, Plan 2, Plan 4, Plan 5, Postgraduate) |
| 204 | - Outstanding balance |
| 205 | - Repayments made via PAYE (if employed) |
| 206 | |
| 207 | **VAT returns:** |
| 208 | - Quarterly turnover and VAT collected (output tax) |
| 209 | - Input VAT claimed |
| 210 | - Flat Rate Scheme percentage applied (if FRS) |
| 211 | - Any VAT owed / refund per quarter |
| 212 | |
| 213 | **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. |
| 214 | |
| 215 | --- |
| 216 | |
| 217 | ## Section 5 -- The confirmation |
| 218 | |
| 219 | After inference, present a single compact summary message. Use a structured format that is fast to scan. Invite the user to correct anything wrong. |
| 220 | |
| 221 | **Example summary message:** |
| 222 | |
| 223 | > Here's what I pulled from your documents. Skim and tell me what's wrong. |
| 224 | > |
| 225 | > **Identity** |
| 226 | > - Jane Smith, single |
| 227 | > - Full-year UK resident (Manchester) |
| 228 | > - Sole trader (freelance software developer) |
| 229 | > - VAT: standard registered (GB 123 4567 89) |
| 230 | > |
| 231 | > **Turnover (from bank statement + invoices)** |
| 232 | > - Gross turnover (ex-VAT): ~GBP 72,000 |
| 233 | > - TechCo Ltd: GBP 42,000 (monthly retainer) |
| 234 | > - DesignHub: GBP 20,000 (project work) |
| 235 | > - Various smaller clients: GBP 10,000 |
| 236 | > - VAT collected (20%): ~GBP 14,400 |
| 237 | > - Non-UK clients (outside scope): GBP 5,000 |
| 238 | > |
| 239 | > **Expenses (from bank statement + purchase invoices)** |
| 240 | > - Software / SaaS: GBP 2,400 |
| 241 | > - Professional insurance: GBP 600 |
| 242 | > - Accountancy fees: GBP 900 |
| 243 | > - Telephone / broadband: GBP 840 (TBD -- need business use %) |
| 244 | > - Motor vehicle: GBP 2,800 fuel + GBP 500 maintenance (TBD -- simplified expenses or actual costs?) |
| 245 | > - MacBook Pro GBP 1,800 (March 2026) -- capital item, AIA |
| 246 | > - Input VAT on purchases: ~GBP 1,500 (reclaimable) |
| 247 | > |
| 248 | > **Employment income (from P60)** |
| 249 | > - Gross employment income: GBP 15,000 (part-time role) |
| 250 | > - Tax deducted via PAYE: GBP 1,200 |
| 251 | > - Class 1 NIC deducted: GBP 720 |
| 252 | > |
| 253 | > **Student loan (from P60 + SLC statement)** |
| 254 | > - Plan 2, threshold GBP 27,295 |
| 255 | > - GBP 400 repaid via PAYE |
| 256 | > - Additional repayment due on SA |
| 257 | > |
| 258 | > **Payments on account (from bank statement / SA302)** |
| 259 | > - 1st payment on account (31 Jan 2026): GBP 3,000 |
| 260 | > - 2nd payment on account (31 Jul 2025): GBP 3,000 |
| 261 | > - Total paid: GBP 6,000 |
| 262 | > |
| 263 | > **Prior year (from 2024/25 SA302)** |
| 264 | > - 2024/25 total SA liability: GBP 8,500 |
| 265 | > - 2024/25 net self-employment profit: GBP 48,000 |
| 266 | > - Payments on account for 2025/26 based on 2024/25: GBP 4,250 x 2 = GBP 8,500 |
| 267 | > |
| 268 | > **VAT (from VAT returns)** |
| 269 | > - Q1-Q3 2025/26 filed |
| 270 | > - Q4 outstanding (Jan-Mar 2026) |
| 271 | > |
| 272 | > **Flags I already see:** |
| 273 | > 1. Telephone / broadband -- need business use percentage |
| 274 | > 2. Motor vehicle -- simplified expenses (45p/mile) or actual costs? |
| 275 | > 3. MacBook Pro GBP 1,800 -- qualifies for AIA, full deduction in year of purchase |
| 276 | > 4. Q4 VAT return not yet filed -- will prepare as part of this workflow |
| 277 | > 5. Student loan Plan 2 -- additional repayment due via Self Assessment |
| 278 | > 6. Employment income present -- will need SA102 (employment supplement) |
| 279 | > |
| 280 | > **Is any of this wrong? Reply "looks good" or tell me what to fix.** |
| 281 | |
| 282 | --- |
| 283 | |
| 284 | ## Section 6 -- Gap filling |
| 285 | |
| 286 | 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. |
| 287 | |
| 288 | **Things that usually cannot be inferred:** |
| 289 | |
| 290 | 1. **Scottish taxpayer** -- Cannot tell from documents (address alone may not determine HMRC's view). Affects income tax rates (Scottish rates differ from rUK rates). |
| 291 | 2. **Simplified expenses election** -- Whether the user uses HMRC simplified expenses for vehicles, use of home, or living at business premises. |
| 292 | 3. **Cash basis** -- Whether the user uses cash basis accounting (default for most sole traders under GBP 150,000 turnover) or traditional accruals. |
| 293 | 4. **Student loan plan** -- Plan type determines repayment threshold and rate. |
| 294 | 5. **Use of home** -- Cannot tell from documents whether a home office is used. Simplified flat rate (GBP 10-26/month based on hours) or actual costs apportionment. |
| 295 | 6. **Capital allowances from prior years** -- Continuing WDA on assets in the pool (unless prior SA103 has the schedule). |
| 296 | 7. **Marriage Allowance** -- Whether transfer of GBP 1,260 personal allowance to/from spouse applies. |
| 297 | 8. **Pension contributions** -- Personal pension payments not visible in business bank (relief at source or net pay). |
| 298 | |
| 299 | **Scottish taxpayer:** |
| 300 | |
| 301 | Call `ask_user_input_v0` with: |
| 302 | |
| 303 | ``` |
| 304 | Q: "Scottish taxpayer?" |
| 305 | Options: [ |
| 306 | "Yes -- my main home is in Scotland (Scottish income tax rates apply)", |
| 307 | "No -- England, Wales, or Northern Ireland", |
| 308 | "Not sure" |
| 309 | ] |
| 310 | ``` |
| 311 | |
| 312 | If yes -> Scottish rates apply: starter 19%, basic 20%, intermediate 21%, higher 42%, advanced 45%, top 48%. |
| 313 | If no -> rUK rates apply: basic 20%, higher 40%, additional 45%. |
| 314 | If not sure -> "Where is your main home? If it's in Scotland, Scottish rates apply. HMRC determines this based on your address." |
| 315 | |
| 316 | **Simplified expenses:** |
| 317 | |
| 318 | Call `ask_user_input_v0` with: |
| 319 | |
| 320 | ``` |
| 321 | Q: "Motor vehicle expenses method?" |
| 322 | Options: [ |
| 323 | "Simplified expenses (flat rate 45p/mile first 10,000, then 25p/mile)", |
| 324 | "Actual costs (fuel, insurance, maintenance, depreciation -- need business use %)", |
| 325 | "No vehicle used for business" |
| 326 | ] |
| 327 | ``` |
| 328 | |
| 329 | If simplified -> ask for total business miles driven in 2025/26. |
| 330 | If actual -> ask for total miles, business miles, and total vehicle costs. Compute business %. |
| 331 | If none -> skip. |
| 332 | |
| 333 | **Use of home:** |
| 334 | |
| 335 | Call `ask_user_input_v0` with: |
| 336 | |
| 337 | ``` |
| 338 | Q: "Use of home for business?" |
| 339 | Options: [ |
| 340 | "Simplified flat rate (GBP 10-26/month based on hours worked at home)", |
| 341 | "Actual costs apportionment (proportion of rent/mortgage, utilities, broadband)", |
| 342 | "Separate business premises (not at home)", |
| 343 | "No home office claim" |
| 344 | ] |
| 345 | ``` |
| 346 | |
| 347 | If simplified -> ask for average hours per month worked at home. 25-50 hrs = GBP 10/month, 51-100 hrs = GBP 18/month, 101+ hrs = GBP 26/month. |
| 348 | If actual -> ask for total household costs and business use percentage. |
| 349 | If separate premises -> rent already captured in expenses. |
| 350 | If none -> skip. |
| 351 | |
| 352 | **Cash basis:** |
| 353 | |
| 354 | Call `ask_user_input_v0` with: |
| 355 | |
| 356 | ``` |
| 357 | Q: "Accounting basis?" |
| 358 | Options: [ |
| 359 | "Cash basis (record income when received, expenses when paid -- most sole traders)", |
| 360 | "Traditional accruals basis (record income when earned, expenses when incurred)" |
| 361 | ] |
| 362 | ``` |
| 363 | |
| 364 | Cash basis is the default for sole traders with turnover under GBP 150,000. Most sole traders should use cash basis. |
| 365 | |
| 366 | Flag all private-use percentages as T2 -- chartered accountant must confirm the percentage is reasonable and documented. |
| 367 | |
| 368 | --- |
| 369 | |
| 370 | ## Section 7 -- The final handoff |
| 371 | |
| 372 | Once gap-filling is done, produce a final handoff message and hand off to `uk-return-assembly`. |
| 373 | |
| 374 | **Example handoff message:** |
| 375 | |
| 376 | > Intake complete. Here's what's going to the return assembly: |
| 377 | > |
| 378 | > Sole trader, single, VAT registered (standard), full-year UK resident (England). Turnover GBP 72,000, estimated net profit ~GBP 58,000 before capital allowances. |
| 379 | > |
| 380 | > I'm now going to run the full UK return preparation. This covers: |
| 381 | > 1. VAT return (Q4 2025/26) |
| 382 | > 2. SA103 self-employment pages (trading income) |
| 383 | > 3. SA100 main return (personal tax computation) |
| 384 | > 4. Class 2 + Class 4 National Insurance |
| 385 | > 5. Student loan repayment (if applicable) |
| 386 | > 6. Payments on account for 2026/27 |
| 387 | > |
| 388 | > You'll get back: |
| 389 | > 1. An Excel working paper with all forms and live formulas |
| 390 | > 2. A reviewer brief with positions, citations, and flags for your accountant |
| 391 | > 3. A filing calendar with all upcoming deadlines |
| 392 | > |
| 393 | > Starting now. |
| 394 | |
| 395 | Then internally invoke `uk-return-assembly` with the structured intake package. |
| 396 | |
| 397 | --- |
| 398 | |
| 399 | ## Section 8 -- Structured intake package (internal format) |
| 400 | |
| 401 | The downstream skill (`uk-return-assembly`) consumes a JSON structure. It is internal and not shown to the user unless they ask. Key fields: |
| 402 | |
| 403 | ```json |
| 404 | { |
| 405 | "jurisdiction": "UK", |
| 406 | "tax_year": "2025/26", |
| 407 | "taxpayer": { |
| 408 | "name": "", |
| 409 | "birth_year": 0, |
| 410 | "marital_status": "single | married | civil_partner", |
| 411 | "residency": "full_year", |
| 412 | "scottish_taxpayer": false, |
| 413 | "utr": "", |
| 414 | "ni_number": "", |
| 415 | "vat_number": "", |
| 416 | "vat_status": "standard | flat_rate_scheme | unregistered", |
| 417 | "flat_rate_pct": 0, |
| 418 | "entity_type": "sole_trader", |
| 419 | "industry": "", |
| 420 | "accounting_basis": "cash | accruals" |
| 421 | }, |
| 422 | "income": { |
| 423 | "gross_turnover_ex_vat": 0, |
| 424 | "vat_collected": 0, |
| 425 | "outside_scope_income": 0, |
| 426 | "employment_income": 0, |
| 427 | "paye_tax_deducted": 0, |
| 428 | "class1_nic_deducted": 0, |
| 429 | "other_income": 0, |
| 430 | "client_breakdown": [] |
| 431 | }, |
| 432 | "expenses": { |
| 433 | "fully_deductible": [], |
| 434 | "mixed_use": [], |
| 435 | "disallowable": [], |
| 436 | "capital_items": [] |
| 437 | }, |
| 438 | "vat": { |
| 439 | "quarterly_returns_filed": [], |
| 440 | "input_vat_reclaimable": 0, |
| 441 | "flat_rate_scheme": false, |
| 442 | "flat_rate_pct": 0 |
| 443 | }, |
| 444 | "student_loan": { |
| 445 | "has_loan": false, |
| 446 | "plan_type": "plan_1 | plan_2 | plan_4 | plan_5 | postgraduate", |
| 447 | "repaid_via_paye": 0, |
| 448 | "outstanding_balance": 0 |
| 449 | }, |
| 450 | "payments_on_account": { |
| 451 | "prior_year_sa_liability": 0, |
| 452 | "first_poa_paid": 0, |
| 453 | "second_poa_paid": 0, |
| 454 | "total_paid": 0 |
| 455 | }, |
| 456 | "prior_year": { |
| 457 | "total_sa_liability": 0, |
| 458 | "net_self_employment_profit": 0, |
| 459 | "capital_allowances_pool": 0 |
| 460 | }, |
| 461 | "home_office": { |
| 462 | "method": "simplified | actual | none", |
| 463 | "hours_per_month": 0, |
| 464 | "actual_costs": 0, |
| 465 | "business_pct": 0, |
| 466 | "annual_amount": 0 |
| 467 | }, |
| 468 | "private_use": { |
| 469 | "motor_vehicle_method": "simplified | actual | none", |
| 470 | "business_miles": 0, |
| 471 | "motor_vehicle_business_pct": 0, |
| 472 | "phone_business_pct": 0, |
| 473 | "broadband_business_pct": 0 |
| 474 | }, |
| 475 | "pension": { |
| 476 | "personal_contributions": 0, |
| 477 | "relief_method": "relief_at_source | net_pay" |
| 478 | }, |
| 479 | "marriage_allowance": { |
| 480 | "transfer_to_spouse": false, |
| 481 | "transfer_from_spouse": false |
| 482 | }, |
| 483 | "open_flags": [], |
| 484 | "refusals_triggered": [], |
| 485 | "documents_received": [] |
| 486 | } |
| 487 | ``` |
| 488 | |
| 489 | --- |
| 490 | |
| 491 | ## Section 9 -- Refusal handling |
| 492 | |
| 493 | Refusals fire from either the refusal sweep (Section 2) or during inference (e.g., Ltd company discovered in documents). |
| 494 | |
| 495 | When a refusal fires: |
| 496 | 1. Stop the workflow |
| 497 | 2. State the specific reason in one sentence |
| 498 | 3. Recommend the path forward (specific practitioner type) |
| 499 | 4. Offer to continue with partial help ONLY if the out-of-scope item is cleanly separable (rare) |
| 500 | |
| 501 | **Do not:** |
| 502 | - Apologize profusely |
| 503 | - Try to work around the refusal |
| 504 | - Suggest the user "might be able to" fit into scope if they answer differently |
| 505 | - Continue silently |
| 506 | |
| 507 | **Sample refusal:** |
| 508 | |
| 509 | > Stop -- you have a registered limited company. I'm set up for sole traders only. Limited companies file CT600 returns with separate rules for corporation tax, directors' remuneration, and dividends. You need a chartered accountant familiar with Ltd company returns. |
| 510 | > |
| 511 | > I can't help with this one. |
| 512 | |
| 513 | --- |
| 514 | |
| 515 | ## Section 10 -- Self-checks |
| 516 | |
| 517 | **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. |
| 518 | |
| 519 | **Check IN2 -- Refusal sweep used ask_user_input_v0.** The first substantive interaction used the interactive tool, not prose questions. |
| 520 | |
| 521 | **Check IN3 -- Upload-first flow honoured.** After refusal sweep, the skill asked for a document dump before asking any content questions. |
| 522 | |
| 523 | **Check IN4 -- Documents were parsed and inferred before asking questions.** The inference summary (Section 5) was shown before gap-filling questions (Section 6). |
| 524 | |
| 525 | **Check IN5 -- Gap-filling only asked about things NOT visible in documents.** If the skill asked "are you VAT registered" after the bank statement showed HMRC VAT payments, check fails. |
| 526 | |
| 527 | **Check IN6 -- Open flags captured.** Anything ambiguous, risky, or attention-worthy during inference is in the `open_flags` list in the handoff package. |
| 528 | |
| 529 | **Check IN7 -- Handoff to `uk-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. |
| 530 | |
| 531 | **Check IN8 -- Reviewer step was stated upfront and reiterated before handoff.** The opening message mentioned chartered accountant signoff. |
| 532 | |
| 533 | **Check IN9 -- Refusals were clean.** No hedging. Stop means stop. |
| 534 | |
| 535 | **Check IN10 -- No meta-commentary about workflow phases.** The skill did not say "Phase 1," "Phase 2," etc. |
| 536 | |
| 537 | **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. |
| 538 | |
| 539 | **Check IN12 -- VAT status was established.** Standard vs FRS vs unregistered was confirmed before inference, as it changes how every transaction is classified. |
| 540 | |
| 541 | **Check IN13 -- Scottish taxpayer status was established.** Determines which income tax rate table applies. |
| 542 | |
| 543 | --- |
| 544 | |
| 545 | ## Section 11 -- Performance targets |
| 546 | |
| 547 | For a prepared user (documents in a folder, ready to upload): |
| 548 | - **Refusal sweep**: 30 seconds (1-2 interactive turns) |
| 549 | - **Document upload**: 2 minutes (1 upload turn) |
| 550 | - **Inference and confirmation display**: 1 minute Claude processing + 1 turn for user confirmation |
| 551 | - **Gap filling**: 2 minutes (2-3 interactive turns) |
| 552 | - **Handoff**: immediate |
| 553 | - **Total**: ~6 minutes |
| 554 | |
| 555 | For an unprepared user (has to go fetch documents): |
| 556 | - Refusal sweep: same |
| 557 | - Document discovery: 10-20 minutes offline |
| 558 | - Rest: same |
| 559 | - **Total**: 15-25 minutes |
| 560 | |
| 561 | --- |
| 562 | |
| 563 | ## Section 12 -- Cross-skill references |
| 564 | |
| 565 | **Inputs:** User-provided documents and answers. |
| 566 | |
| 567 | **Outputs:** Structured intake package consumed by `uk-return-assembly`. |
| 568 | |
| 569 | **Downstream skills triggered (via uk-return-assembly):** |
| 570 | - `uk-vat-return` -- VAT100 quarterly return (if VAT registered) |
| 571 | - `uk-self-employment-sa103` -- SA103 self-employment pages (trading income) |
| 572 | - `uk-income-tax-sa100` -- SA100 main return (personal tax computation) |
| 573 | - `uk-national-insurance` -- Class 2 + Class 4 NIC |
| 574 | - `uk-student-loan-repayment` -- Student loan repayment via Self Assessment (if applicable) |
| 575 | - `uk-payments-on-account` -- Payments on account for 2026/27 |
| 576 | |
| 577 | --- |
| 578 | |
| 579 | ### Change log |
| 580 | |
| 581 | - **v0.1 (April 2026):** Initial draft. Upload-first, inference-then-confirm pattern modelled on mt-freelance-intake v0.1. |
| 582 | |
| 583 | ## End of Intake Skill v0.1 |
| 584 | |
| 585 | |
| 586 | --- |
| 587 | |
| 588 | ## Disclaimer |
| 589 | |
| 590 | 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 chartered accountant, ACCA member, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 591 | |
| 592 | 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. |
| 593 |
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 UK tax returns AND mentions freelancing, self-employment, sole trading, contracting, or side hustle income. Trigger on phrases like "help me do my UK taxes", "prepare my self-assessment", "I'm self-employed in the UK", "I'm a sole trader", "do my SA100", "prepare my tax return", or any similar phrasing where the user is a UK-resident self-employed individual needing tax return preparation. This is the REQUIRED entry point for the UK self-employed tax workflow -- every other skill in the stack (uk-vat-return, uk-self-employment-sa103, uk-income-tax-sa100, uk-national-insurance, uk-student-loan-repayment, uk-payments-on-account, uk-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. UK full-year residents only; sole traders.
GBty-2025