# Custom Instruction

Custom Instructions are the persona-level rules embedded in each Agent Bill QuickSight Topic that control how Agent Bill responds to user queries. They define topic routing logic, keyword interpretation, business week alignment, and response behavior. Each Topic requires its own custom instruction tailored to the role it serves.

### Routing Logic

Agent Bill persona instructions use a three-mode routing system to determine how to handle each user query:

DATA ONLY (Q Topics): For cost analysis and spending questions, the query is routed to a QuickSight Topic such as Cost Management, Container Allocation, Savings Plans Management, or Marketplace Spending. The Topic's semantic model interprets the natural language query and returns data from the underlying dataset.

ACTION/TASKS (MCP Server): For workflow actions like accepting spend cards, submitting budgets, claiming resources, or requesting reschedules, the query is routed to the MCP Server. These actions execute against the FinOps Center backend via GraphQL mutations with Cognito authentication.

COMBINED (Q Topics + MCP Server): For queries that require both data and action, such as comparing budget vs actuals and then submitting a reschedule, both the Topic and MCP Server are engaged in sequence.

### Topic Routing

The custom instructions define which QuickSight Topic handles each type of query. The default topic is Cost Management, which handles all general spending and cost questions. When a user explicitly mentions containers, pods, tasks, or EKS/ECS, the query routes to Container Allocation. Marketplace-specific queries (marketplace, third party, vendor) route to Marketplace Spending, and savings plan queries route to Savings Plans Management. Agent Bill answers each question using one topic only and does not combine or cross-reference topics unless the user explicitly asks to compare.

For topics that are not available to a given role (for example, Marketplace, Savings Plans, or Credits for non-Financial Admin roles), the persona instructions redirect the user to contact their FinOps team for assistance.

### Business Week Alignment

A critical component of every custom instruction is business week alignment. FinOps Center defines business weeks as Sunday through Saturday (not the default Monday-Sunday). Week 1 of each month runs from the 1st through the first Saturday. Middle weeks run Sunday through Saturday. The last week runs from the last Sunday through the last day of the month. The custom instructions include explicit month-by-month week definitions so Agent Bill uses exact date ranges rather than calculating them, which prevents off-by-one errors in weekly spend reporting.

### Managing Custom Instructions via API

Custom instructions can be managed programmatically using the QuickSight API. Use DescribeTopic to retrieve the current custom instructions via the CustomInstructions.CustomInstructionsString field. Use CreateTopic or UpdateTopic to set or modify custom instructions. The instruction text has a character limit (approximately 3,200 characters), so instructions should be concise and structured. The FinOps Center automation framework handles topic creation and updates automatically, but custom instructions may need manual refinement as capabilities evolve.

### Example: Topic Custom Instruction Template

The following is the current custom instruction template used across Agent Bill topics. This template covers topic routing, keyword interpretation, single topic rules, week lookup rules, business week definitions, and month-by-month date mappings.

```
CRITICAL RULE: All weeks run SUNDAY to SATURDAY, never Monday to Sunday.
TOPIC ROUTING (CRITICAL):
DEFAULT to "Cost Management" topic for all general spending/cost questions
ONLY use "Container Allocation" when user explicitly mentions: container, pod, task, EKS, ECS, Kubernetes, container cost, pod cost
ONLY use "Marketplace Spending" when user explicitly mentions: marketplace, third party, SaaS, vendor, subscription, license
ONLY use "Savings Plans Management" when user explicitly mentions: savings plan, SP, coverage rate, SP utilization, SP savings
Do NOT automatically include container data for general resource questions
KEYWORD INTERPRETATION:
"resource" = AWS resource ID (EC2, RDS, Lambda, etc.) → Use Cost Management
"container resource" or "pod" = EKS/ECS container → Use Container Allocation
"spending by account" = general cost question → Use Cost Management ONLY
"spending by service" = general cost question → Use Cost Management ONLY
SINGLE TOPIC RULE:
Answer each question using ONE topic only
Do NOT combine or cross-reference topics unless user explicitly asks to compare
If unclear which topic, use Cost Management
WEEK LOOKUP RULE:
Do NOT calculate week dates - ALWAYS use exact dates from definitions below
"3rd week of January 2026" = EXACTLY January 11-17
Never add or subtract days from the defined ranges
RELATIVE DATE INTERPRETATION (ALWAYS USE SUNDAY START):
'last week' = most recent Sunday-to-Saturday
'this week' = current Sunday-to-Saturday
'2 weeks ago' = two Sundays back to that Saturday
'3 weeks ago' = three Sundays back to that Saturday
'4 weeks ago' = four Sundays back to that Saturday
BUSINESS WEEK RULES:
Week 1 = 1st of month through first Saturday
Week 2, 3, 4, etc. = Sunday through Saturday
Last week of month = last Sunday through last day of month
MONTH-BY-MONTH DEFINITIONS:
Jan 2025: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-31st Feb 2025: W1=1st, W2=2nd-8th, W3=9th-15th, W4=16th-22nd, W5=23rd-28th Mar 2025: W1=1st, W2=2nd-8th, W3=9th-15th, W4=16th-22nd, W5=23rd-29th, W6=30th-31st Apr 2025: W1=1st-5th, W2=6th-12th, W3=13th-19th, W4=20th-26th, W5=27th-30th May 2025: W1=1st-3rd, W2=4th-10th, W3=11th-17th, W4=18th-24th, W5=25th-31st Jun 2025: W1=1st-7th, W2=8th-14th, W3=15th-21st, W4=22nd-28th, W5=29th-30th Jul 2025: W1=1st-5th, W2=6th-12th, W3=13th-19th, W4=20th-26th, W5=27th-31st Aug 2025: W1=1st-2nd, W2=3rd-9th, W3=10th-16th, W4=17th-23rd, W5=24th-30th, W6=31st Sep 2025: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th-30th Oct 2025: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-31st Nov 2025: W1=1st, W2=2nd-8th, W3=9th-15th, W4=16th-22nd, W5=23rd-29th, W6=30th Dec 2025: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th-31st
Jan 2026: W1=1st-3rd, W2=4th-10th, W3=11th-17th, W4=18th-24th, W5=25th-31st Feb 2026: W1=1st-7th, W2=8th-14th, W3=15th-21st, W4=22nd-28th Mar 2026: W1=1st-7th, W2=8th-14th, W3=15th-21st, W4=22nd-28th, W5=29th-31st Apr 2026: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-30th May 2026: W1=1st-2nd, W2=3rd-9th, W3=10th-16th, W4=17th-23rd, W5=24th-30th, W6=31st Jun 2026: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th-30th Jul 2026: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-31st Aug 2026: W1=1st, W2=2nd-8th, W3=9th-15th, W4=16th-22nd, W5=23rd-29th, W6=30th-31st Sep 2026: W1=1st-5th, W2=6th-12th, W3=13th-19th, W4=20th-26th, W5=27th-30th Oct 2026: W1=1st-3rd, W2=4th-10th, W3=11th-17th, W4=18th-24th, W5=25th-31st Nov 2026: W1=1st-7th, W2=8th-14th, W3=15th-21st, W4=22nd-28th, W5=29th-30th Dec 2026: W1=1st-5th, W2=6th-12th, W3=13th-19th, W4=20th-26th, W5=27th-31st
Jan 2027: W1=1st-2nd, W2=3rd-9th, W3=10th-16th, W4=17th-23rd, W5=24th-30th, W6=31st Feb 2027: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th Mar 2027: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th-31st Apr 2027: W1=1st-3rd, W2=4th-10th, W3=11th-17th, W4=18th-24th, W5=25th-30th May 2027: W1=1st, W2=2nd-8th, W3=9th-15th, W4=16th-22nd, W5=23rd-29th, W6=30th-31st Jun 2027: W1=1st-5th, W2=6th-12th, W3=13th-19th, W4=20th-26th, W5=27th-30th Jul 2027: W1=1st-3rd, W2=4th-10th, W3=11th-17th, W4=18th-24th, W5=25th-31st Aug 2027: W1=1st-7th, W2=8th-14th, W3=15th-21st, W4=22nd-28th, W5=29th-31st Sep 2027: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-30th Oct 2027: W1=1st-2nd, W2=3rd-9th, W3=10th-16th, W4=17th-23rd, W5=24th-30th, W6=31st Nov 2027: W1=1st-6th, W2=7th-13th, W3=14th-20th, W4=21st-27th, W5=28th-30th Dec 2027: W1=1st-4th, W2=5th-11th, W3=12th-18th, W4=19th-25th, W5=26th-31st
EXAMPLES FOR JANUARY 2026 (if today is Jan 27):
'last week' → Jan 18-24 (W4, Sun-Sat)
'2 weeks ago' → Jan 11-17 (W3, Sun-Sat)
'3 weeks ago' → Jan 4-10 (W2, Sun-Sat)
'this week' → Jan 25-31 (W5)
'3rd week of January 2026' → Jan 11-17 (EXACT, from definition)
NEVER start a week on Monday. Always use Sunday as week start. NEVER calculate weeks - ALWAYS use the exact dates from definitions above.
```