Skip to main content

Organizing Rules

As your rule set grows, organization becomes critical. Well-organized rules are easier to find, maintain, and troubleshoot. This guide shares strategies for structuring rule sets that scale from a handful to hundreds of rules.

Good organization prevents chaos and makes your Dynamic Screen Rules implementation sustainable over time.

Why Organization Matters​

Small rule sets (1-10 rules):

  • Organization is nice to have
  • Can manage without strict structure
  • Descriptive names are usually enough

Medium rule sets (10-50 rules):

  • Organization becomes important
  • Hard to find specific rules without structure
  • Naming conventions prevent confusion

Large rule sets (50+ rules):

  • Organization is critical
  • Impossible to maintain without clear structure
  • Systematic approach required

Benefits of good organization:

  • Find rules quickly when troubleshooting
  • Understand rule dependencies
  • Avoid creating duplicate rules
  • Onboard new team members faster
  • Identify gaps in coverage

Grouping Strategies​

Group by Screen​

Strategy: Organize rules by where they apply (Global Issue Create, Issue View, Issue Transition).

Why this works:

  • Screen determines context and capabilities
  • Rules on same screen often relate to similar user workflows
  • Easy to review all rules affecting a specific user experience

Naming convention:

[Create] Show Root Cause for High Priority Bugs
[Create] Require Description for Features
[Create] Pre-fill Component for Backend Bugs

[View] Lock Fix Versions in Done Status
[View] Show Budget for Finance Team
[View] Hide Sensitive Fields from External Users

[Transition] Require Test Results when Moving to Release
[Transition] Pre-fill Resolution for Bug Closure
[Transition] Lock Fields During Review

Directory structure (if exporting rules):

rules/
├── global-issue-create/
│   ├── progressive-disclosure-rules.md
│   ├── validation-rules.md
│   └── pre-fill-rules.md
├── issue-view/
│   ├── field-locking-rules.md
│   └── role-based-visibility-rules.md
└── issue-transition/
    ├── transition-validation-rules.md
    └── status-based-rules.md

When to use: Best for teams focused on optimizing specific user workflows.

Group by Concern​

Strategy: Organize rules by what they do (validation, visibility, pre-fill, locking).

Why this works:

  • Logical grouping by purpose
  • Easy to find all validation rules or all visibility rules
  • Helps identify patterns and reduce duplication

Naming convention:

[Validation] Require Root Cause for Critical Bugs
[Validation] Require Budget Code for Expensive Features
[Validation] Require Test Results Before Release

[Visibility] Show Root Cause for High Priority
[Visibility] Show Budget for Finance Team
[Visibility] Hide Internal Notes from External Users

[Pre-fill] Set Component = Backend for Backend Bugs
[Pre-fill] Set Due Date = Next Business Day
[Pre-fill] Set Assignee = Team Lead for Critical

[Locking] Lock Fix Versions in Done Status
[Locking] Lock Priority After Testing Starts
[Locking] Lock Fields for Non-Managers

Categories:

  • Validation - Make Field Required rules
  • Visibility - Show/Hide Field rules
  • Pre-fill - Set Field Value rules
  • Locking - Lock Field (Read-Only) rules
  • Options - Limit Field Options rules
  • Labels - Change Field Label/Description rules

When to use: Best for teams with many rules performing similar functions across screens.

Group by Project or Issue Type​

Strategy: Organize rules by which project or issue type they target.

Why this works:

  • Project-specific rules stay together
  • Easy to review all rules for a specific project
  • Helps when migrating or archiving projects

Naming convention:

[SUPPORT] Show Customer Tier for All Issues
[SUPPORT] Require SLA Deadline for Premium
[SUPPORT] Lock Fields for External Users

[DEV] Show Root Cause for High Priority Bugs
[DEV] Require Test Coverage for Stories
[DEV] Pre-fill Sprint for Current Sprint Issues

[Bug] Require Steps to Reproduce
[Bug] Show Root Cause for Critical Priority
[Bug] Lock in Done Status

[Feature] Require Business Justification over $10k
[Feature] Show Budget Fields for Finance
[Feature] Pre-fill Estimated Cost

When to use: Best for teams managing many projects with distinct workflows.

Strategy: Combine grouping methods for maximum clarity.

Format: [Screen] [Concern] Description

Examples:

[Create] [Validation] Require Root Cause for Critical Bugs
[Create] [Visibility] Show Budget for Finance Team
[Create] [Pre-fill] Set Due Date = Next Business Day

[View] [Locking] Lock Fix Versions in Done Status
[View] [Visibility] Hide Sensitive Fields from External Users

[Transition] [Validation] Require Test Results Before Release

Why hybrid works best:

  • Screen tells you where it applies
  • Concern tells you what it does
  • Description tells you when it applies
  • Complete context at a glance

Naming Conventions​

Anatomy of a Good Rule Name​

Format: [Context] [Action] [Field] [Condition]

Components:

  • Context - Screen, Project, or Concern (optional but recommended)
  • Action - Show, Hide, Require, Lock, Set, Limit
  • Field - Which field is affected
  • Condition - When rule applies (brief)

Examples:

[Create] Show Root Cause for High Priority
[View] Lock Fix Versions in Done Status
[Transition] Require Test Results when Moving to Release
[SUPPORT] Pre-fill SLA Deadline for Premium Customers
[Validation] Require Business Justification over $10k

Consistent Prefixes​

Use consistent prefixes for categories:

By Screen:

  • [Create] - Global Issue Create
  • [View] - Issue View
  • [Transition] - Issue Transition

By Concern:

  • [Validation] - Make Field Required
  • [Visibility] - Show/Hide Field
  • [Pre-fill] - Set Field Value
  • [Locking] - Lock Field
  • [Options] - Limit Field Options
  • [Labels] - Change Field Label/Description

By Project:

  • [SUPPORT] - Support project
  • [DEV] - Development project
  • [OPS] - Operations project

By Priority/Importance:

  • [CRITICAL] - Must not be disabled
  • [IMPORTANT] - Core business logic
  • [OPTIONAL] - Nice-to-have convenience

Naming Anti-Patterns to Avoid​

Too vague:

❌ Bug Rule
❌ Field Rule 1
❌ Important Rule

Too verbose:

❌ Show the Root Cause field when the user creates a Bug issue
   and selects High or Critical priority in the Global Issue Create dialog

Inconsistent:

❌ Show Root Cause - High Priority
❌ Root cause visible when priority=high
❌ [RootCause] Visibility - High

Better:

✅ [Create] Show Root Cause for High Priority Bugs
✅ [Create] Show Root Cause for Critical Bugs
✅ [View] Lock Root Cause in Done Status

Documentation Strategies​

Maintain a Rule Inventory​

Create a master list of all rules with:

  • Rule name
  • Screen (Create/View/Transition)
  • Target field
  • Conditions summary
  • Action type
  • Business rationale
  • Date created
  • Created by
  • Last modified

Example inventory (spreadsheet or markdown table):

Rule NameScreenFieldConditionsActionWhyCreatedBy
[Create] Show Root Cause for High Priority BugsCreateRoot CausePriority = High OR Critical, Issue Type = BugShowCritical bugs need root cause analysis per QA process2024-03-15Jane
[View] Lock Fix Versions in DoneViewFix VersionsStatus = DoneLockPrevent version changes after QA testing2024-03-20Bob

Benefits:

  • Single source of truth for all rules
  • Easy to search and filter
  • Historical record of changes
  • Helps identify redundancy

Document Rule Dependencies​

Track which rules depend on or interact with each other:

Example dependency documentation:

Rule: [Create] Require Root Cause for Critical Bugs
Depends on: [Create] Show Root Cause for High Priority Bugs
Reason: Field must be visible before it can be required
Notes: If "Show" rule is disabled, "Require" rule will fail

Dependency types:

  • Show before Require - Can't require hidden field
  • Condition on same field - Multiple rules checking same field value
  • Sequential disclosure - Field A shows Field B, Field B shows Field C
  • Conflicting rules - Two rules trying to hide/show same field

Document Business Rationale​

For each rule, explain:

  • What: What does the rule do? (covered by name)
  • Why: Why does this rule exist? (business requirement)
  • Who: Who requested it? (stakeholder, team)
  • When: When was it approved? (date)

Example:

Rule: [Create] Require Business Justification over $10k

What: Makes "Business Justification" field required when
      Estimated Cost > $10,000 on Feature issues

Why: Finance department requires written justification for
     all features exceeding $10k budget threshold

Who: Requested by Finance team (Sarah Johnson)
     Approved by Product Management (Mike Chen)

When: Approved Q2 2024, implemented 2024-04-15

Notes: Budget threshold may be adjusted annually
       Review policy in Q1 each year

Rule Organization Checklist​

Use this checklist when organizing your rule set:

Naming:

  • ☐ Consistent naming convention applied to all rules
  • ☐ Rule names describe what rule does and when
  • ☐ Prefixes used for grouping (screen, concern, or project)
  • ☐ No generic names like "Rule 1" or "Bug Rule"

Grouping:

  • ☐ Rules organized by screen, concern, or project
  • ☐ Logical grouping strategy documented and communicated
  • ☐ Easy to find rules affecting specific field or screen

Documentation:

  • ☐ Master rule inventory maintained
  • ☐ Business rationale documented for each rule
  • ☐ Dependencies between rules identified
  • ☐ Rule ownership clear (who created, who maintains)

Maintenance:

  • ☐ Process for reviewing and updating rules
  • ☐ Process for archiving or deleting obsolete rules
  • ☐ New team members can understand rule set

Reorganization: When and How​

Signs You Need to Reorganize​

Warning signs:

  • Can't find specific rule without searching every rule
  • Creating duplicate rules because existing ones are hard to find
  • New team members confused by rule organization
  • Rules have inconsistent naming (some with prefixes, some without)
  • No clear grouping strategy

How to Reorganize​

1. Audit existing rules:

  • Export or list all current rules
  • Group rules by logical categories
  • Identify duplicates or conflicts
  • Note which rules are actually used

2. Choose organization strategy:

  • Decide on grouping approach (screen, concern, project, or hybrid)
  • Define naming convention
  • Document the strategy

3. Rename rules systematically:

  • Rename one category at a time
  • Use consistent prefixes
  • Update documentation as you go

4. Create rule inventory:

  • List all rules with metadata
  • Document dependencies
  • Note business rationale

5. Archive obsolete rules:

  • Identify unused rules
  • Disable (don't delete immediately)
  • Monitor for 2-4 weeks
  • Delete if truly unused

6. Communicate changes:

  • Inform team of new organization
  • Update team documentation
  • Train new admins on organization strategy

Multi-Project Organization​

When Managing Rules Across Multiple Projects​

Challenge: Rules are per-project, so each project has its own rule set.

Strategies:

1. Template approach:

  • Create "template" rules for common patterns
  • Copy to new projects as needed
  • Maintain template documentation

2. Consistent naming across projects:

  • Use same naming convention in all projects
  • Makes it easier to recognize patterns
  • Simplifies knowledge transfer

3. Shared documentation:

  • Maintain central wiki or README with rule patterns
  • Link to project-specific rule lists
  • Document project-specific variations

Example structure:

Documentation/
├── Rule-Templates/
│   ├── progressive-disclosure-templates.md
│   ├── validation-templates.md
│   └── pre-fill-templates.md
├── Project-Rules/
│   ├── support-project-rules.md
│   ├── dev-project-rules.md
│   └── ops-project-rules.md
└── Rule-Organization-Guide.md (this guide)

Team Collaboration​

When Multiple Admins Manage Rules​

Establish conventions:

  • Agree on naming convention
  • Decide on grouping strategy
  • Document in team wiki

Communication:

  • Notify team before creating new rules
  • Document rule purpose and rationale
  • Review rules together periodically

Ownership:

  • Assign rule owners (who maintains each rule)
  • Track who created each rule
  • Coordinate changes

Version control (optional):

  • Export rules to JSON or documentation
  • Commit to version control (git)
  • Track changes over time

Design:

Testing:

Management:

Pitfalls:

Well-organized rules are self-documenting and maintainable. Invest time in organization early - it pays dividends as your rule set grows.