The "Hometax-Doum" (Hometax Help) repository provides a suite of AI-driven skills designed to assist freelancers and individual business owners in navigating the Korea National Tax Service (NTS) "Hometax" platform. The project acts as a guided procedural assistant that helps users prepare and verify tax filings (VAT, Comprehensive Income Tax, and electronic tax invoices) up until the final submission, while strictly adhering to safety and legal boundaries.

Core Methodology and Functional Architecture

The system operates as an interactive AI agent (compatible with Claude, Codex, and Aside) that uses a "Human-in-the-Loop" architecture. The agent never executes final administrative actions (submission, payment, or issuance) on behalf of the user; instead, it provides step-by-step guidance, data reconciliation, and input verification.

1. Guided Procedural Assistance: The system follows a logic-gate approach where the agent prompts the user to navigate specific Hometax screens. It translates high-level user intents (e.g., "Help me with VAT filing") into specific, actionable instructions, identifying potential pitfalls such as missing deduction opportunities (e.g., electronic filing tax credits or electronic tax invoice issuance credits).
2. Data Verification and Error Mitigation: The system performs "cross-validation" by comparing user-provided data (e.g., Excel-based receipt/card logs) against the official Hometax screen inputs. For electronic tax invoices, it implements a digital check for input errors, such as decimal point/digit mismatches (e.g., comparing user-stated "2 million KRW" against an entered "20 million KRW").
3. Proactive Compliance Logic: The repository embeds business logic based on tax law criteria. For instance, it distinguishes between the preceding year’s supply value ($\text{Supply Value}_{n-1}$) for determining simplified taxpayer status ($\S61$) and the current year's standards for tax exemption ($\S69$).

Pro-Tier Analytical Engines

Beyond the free procedural guidance, the system offers two specialized computational engines for predictive analysis:

• Comprehensive Income Tax (CIT) Engine (jongsose-prep-kr): This module performs independent tax calculations using current-year tax rates ($\tau$) and government-verified tables. It calculates the expected tax liability ($T_{exp}$) by aggregating multiple income streams ($I_{total} = I_{labor} + I_{business}$) and applying appropriate deductions ($D$) and credits ($C$):

$$T_{exp} = (I_{total} \cdot \tau) - D - C$$
It also validates the selection between simplified ledger filing versus standard expense ratio filing.

• Withholding Tax Engine (withholding-tax-hometax): This engine automates the computation of withholding amounts for employees and freelancers based on the NTS simplified tax tables. It handles complex variables, such as dependent deductions and social security adjustments, facilitating the creation of withholding tax reports.

Safety, Legal, and Ethical Framework

The system is designed with a "Safety-First" constraint framework:

• Information Integrity: AI agents are prohibited from hallucinating financial values; all numbers must be anchored in the Hometax interface.
• Privacy: The agent enforces masking of sensitive identifiers (resident registration numbers, bank accounts) and prevents the storage of login credentials (passwords, OTPs).
• Legal Disclaimer: In accordance with the Certified Tax Accountant Act (Articles 2 and 20), the tools explicitly state they are not performing "tax representation" or professional consultation. The responsibility for the final submission rests exclusively with the taxpayer, and the software serves only as a procedural aid to ensure readiness.