> For the complete documentation index, see [llms.txt](https://help.filed.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.filed.com/reference/troubleshooting/rules-explainer.md). # Rules explainer {% embed url="" %} ## What rules and protocols are Rules (also called protocols) are firm-level instructions that tell Filed's AI Reviewer how to handle specific situations on future runs. Examples include: * Always flagging a particular line item * Applying a firm-specific convention * Adjusting the severity of a known issue * Skipping a flag the firm has already reviewed and accepted Rules are stored per workspace and are scoped to a return type (such as 1040) or optionally applied across all return types. Rules created or edited by a user belong to that user's personal set (USER kind). Rules that have been promoted and approved for the whole firm are workspace-level rules (WORKSPACE kind). Both kinds are managed through the Playbook section of Filed. ## How Filed applies rules When the AI Reviewer runs for a client, Filed loads the active rules for the matching return type into the processing environment. The AI Reviewer reads those rules as part of its analysis and uses them to shape its output - which issues it raises, how it classifies severity, and what guidance it attaches to each finding. A key consequence of this mechanism: changes to rules only affect future runs. A review that has already completed was processed against the rules as they existed at that time. Editing or adding a rule will not change an already-completed review. To see updated rules reflected on a return, re-run the review after saving the rule change. ## Editing an existing rule Protocols are authored and edited through the **Chat** assistant, not through a field-by-field form. To find your protocols, open **Playbook** and pick the matching task type; to change one, describe the change in Chat. **Walkthrough: edit a protocol** 1. In any Chat, name the protocol and describe the change - for example, "update my verify-box1-wages-prior-year protocol to flag variance over 15%." The assistant revises the protocol and re-proposes it under the same name, so approving the revision updates it in place rather than creating a duplicate. ![The assistant re-proposing a protocol with the revised body](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image2.webp) 2. Click **Save protocol**. The updated protocol then reflects the change in the Playbook list. See [Creating protocols](/reference/playbook/creating-protocols.md) for the full authoring flow. ### What makes a well-formed rule A clear rule has three elements: * **A specific condition** that identifies when it applies * **An unambiguous action** that tells the AI Reviewer what to do in that situation * **An accurate return-type scope** so the rule is not applied to returns it was never intended for Common mistakes to avoid: * **A condition that is too broad**, triggering on situations the rule was not meant to cover * **The wrong return type**, causing the rule to apply to business returns when only 1040 was intended * **An ambiguous action**, such as "review carefully" instead of "flag as high severity" or "suppress this finding" ## Creating a new rule New protocols are also created through Chat. You describe the rule in plain language and the assistant proposes a structured protocol - it auto-generates the kebab-case name, infers the task type from your conversation, and drafts the description and body for you to review. **Walkthrough: create a protocol** 1. In Chat, state the rule ("remember to...", "whenever you do tax prep...", "always check..."). The assistant proposes a protocol with a name, a description (the trigger), and a body (the instruction). Refine it through conversation if needed, then click **Save protocol**. ![The protocol proposal panel with name, description, and body](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image2.webp) 2. Open **Playbook** and select the matching task type to confirm the protocol appears in the **Yours** section with an **Active** status badge. ![The saved protocol in Playbook with an Active badge](https://storage.googleapis.com/filed-prod-public-assets/walkthroughs/protocol-create-chat/image4.webp) For the full step-by-step, see [Creating protocols](/reference/playbook/creating-protocols.md). ### Rule creation tips Start narrow. Write a rule that targets one specific condition, run it on a small set of returns, and observe whether the AI Reviewer output reflects the intended change. Broaden the rule's scope only after confirming it behaves as expected in the narrow case. Avoid writing rules with overlapping conditions. If two rules target the same situation and give conflicting instructions, the AI Reviewer's behavior on that case will be unpredictable. Review the existing rules list before adding a new one to check for potential conflicts. ## Troubleshooting rules that do not apply If a rule exists in Filed but the AI Reviewer output does not reflect it, check the following: **Return type scope.** If the rule is scoped to a specific return type (for example, 1040) and the return being reviewed is a different type, the rule will not apply. Open the rule and confirm the return type setting matches the return you are testing against. **Timing.** Rules only apply to runs that start after the rule was saved. If you edited or created the rule after a review was already completed, that completed review will not reflect the change. Re-run the review to pick up the updated rules. **Rule status.** A rule that has been submitted for workspace promotion but not yet approved may not be active at the workspace level. Check the rule's status in Playbook. **Conflicting rules.** Another rule with a broader or overlapping condition may be overriding the specific rule. Review the full rules list for conflicts. ## When to contact support Contact Filed support if: * Rule edits are confirmed saved and future runs still do not reflect the change * You are seeing unexpected interactions between rules that you cannot resolve by editing * You need to bulk-import or export rules for your workspace Include the rule name, the return type it is scoped to, and a description of the expected AI Reviewer output versus what you actually observed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.filed.com/reference/troubleshooting/rules-explainer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.