Update to EduOpus

{
  "name": "eduopus-principal-skills",
  "description": "Operational guidelines, tool coordination patterns, fuzzy entity resolution, disambiguation rules, and safety protocols for the EduOpus School Principal MCP tool suite.",
  "included_files": [
    {
      "relative_path": "examples/workflows.md",
      "size_in_bytes": 2559
    }
  ],
  "skill_md_contents": "---\nname: eduopus-principal-skills\ndescription: Operational guidelines, tool coordination patterns, fuzzy entity resolution, disambiguation rules, and safety protocols for the EduOpus School Principal MCP tool suite.\n---\n\n# EduOpus Principal MCP Skill Guide\n\nThis skill guides OpenAI models on how to safely, accurately, and effectively orchestrate the **EduOpus School Principal MCP Tool Suite**. All tools operate with strict Row Level Security (RLS) under the authenticated Principal's school context.\n\n---\n\n## 1. Class Name Resolution Protocol\n\n### The Challenge\nSchool class names in databases often differ in formatting from natural user phrasing (e.g., a class named `\"5\"` or `\"Class 10A\"` vs. user input `\"5th\"`, `\"grade 5\"`, `\"Grade 10-A\"`).\n\n### Protocol\n1. **Never Guess or Require Exact Case/Punctuation**:\n   - Before calling tools like `get_class_roster`, `get_fee_status`, `mark_attendance`, `create_homework_assignment`, or `add_student`, check the school's active classes using `get_school_overview` or `get_attendance_summary`.\n2. **Apply Fuzzy Token Matching**:\n   - Normalize numerical suffixes (`\"1st\" -> \"1\"`, `\"5th\" -> \"5\"`, `\"12th\" -> \"12\"`).\n   - Strip redundant prefixes (`\"Class 10A\"` matches `\"10A\"`, `\"Grade 10 A\"`, or `\"10-A\"`).\n3. **Handle Ambiguity / No Confident Match**:\n   - If user input does not cleanly resolve to a single class in the school's roster, **do not fail silently or guess**.\n   - List the active classes currently registered in the school and politely ask the principal:\n     > *\"I couldn't find a class matching '7th B'. Here are the active classes in your school: [Class 7A, Class 7, Class 8A]. Which one did you mean?\"*\n\n---\n\n## 2. Student Disambiguation Protocol\n\n### The Challenge\nMultiple students across different classes (or within the same class) may share similar or identical names (e.g., *\"Rahul Sharma\"*). However, asking for confirmation when the user was already specific creates unnecessary friction.\n\n### Protocol\n1. **Pre-Query Context Narrowing (One-Shot Resolution)**:\n   - Before calling `get_student_details` with just a raw name, check if the user's prompt or conversation history already contains narrowing context (e.g., a class name, a grade like *\"in 5th\"*, or a section mentioned earlier).\n   - If narrowing context exists, pass it immediately as the `class_name` parameter on the very first tool call. Genuinely specific requests (e.g., *\"Show fee details for Aarav in Class 5\"*) will resolve in one shot without ever triggering `multiple_matches_found`.\n2. **Conversational Entity Continuity (Follow-Up Actions)**:\n   - If a student was already confirmed/selected earlier in the same conversation and the user's next message clearly continues referring to the same student (e.g., *\"also mark her present today\"*, *\"what about his pending fee receipts?\"*), **reuse that same `student_identifier` directly** without re-asking.\n3. **Ambiguity Resolution (When True Ambiguity Exists)**:\n   - If `get_student_details` or student search tools return `multiple_matches_found: true` (or a candidate list without enough context to distinguish):\n     - **Never auto-select or guess the first match.**\n     - Present the disambiguation list clearly with:\n       - **Full Name**\n       - **Class / Section**\n       - **Student Identifier** (e.g., `STU-1767344857114`)\n       - **Guardian Name**\n     - Ask the principal to clarify which student they mean before executing further actions.\n4. **Core Rule**:\n   - Disambiguation should only ever interrupt the conversational flow when the AI genuinely cannot tell which student is meant — never as a redundant blanket confirmation step.\n\n---\n\n## 3. Dynamic Fee Status Interpretation\n\n### The Challenge\nEduOpus calculates fee balances dynamically using time-based elapsed billing cycles from the student's `joining_date`, rather than static ledger balances.\n\n### Protocol\n1. **Live Data Over Previous Chat Memory**:\n   - Always query `get_fee_status` fresh. Never rely on numbers from earlier conversational turns.\n2. **Interpret Accruals Accurately**:\n   - A student showing `remaining_fee: 0` in an earlier month may now have an active pending balance if a new monthly billing cycle has started.\n3. **Explain Clearly**:\n   - When presenting fee reports to the principal, distinguish between:\n     - **Total Expected Fees** (annual/monthly accrued)\n     - **Collected Fees** (paid to date)\n     - **Remaining / Overdue Fees** (currently outstanding)\n     - **Net Profit / Settlement Metrics** (if school-wide totals are requested)\n\n---\n\n## 4. Write Action Confirmation & Dry-Run Protocols\n\n### The Challenge\nModifying school records (attendance, student profiles, homework assignments) directly impacts students, teachers, and parents.\n\n### Protocol\nBefore invoking any of the 6 write tools:\n- `mark_attendance`\n- `add_student`\n- `update_student`\n- `bulk_import_students`\n- `create_homework_assignment`\n- `review_homework_submission`\n\n### Required Workflow:\n1. **Plain-Language Summary & Confirmation**:\n   - State exactly what changes will be recorded (target class, dates, names, updated values).\n   - Require explicit user affirmation (*\"Yes, proceed\"*) before sending the execution tool call.\n2. **Special Rule for `bulk_import_students`**:\n   - **Phase 1 (Mandatory Dry-Run)**: Always invoke `bulk_import_students` with `dry_run: true` first.\n   - Present the preview table: total valid records, detected duplicates/conflicts, and the `confirmation_token`.\n   - **Phase 2 (Commit)**: Only after the principal reviews and confirms the preview, call `bulk_import_students` with `dry_run: false` and the returned `confirmation_token`.\n3. **Attendance Overwrites**:\n   - If `mark_attendance` indicates an existing record was overwritten (e.g., modifying a status previously marked by a teacher), highlight the diff clearly to the principal.\n\n---\n\n## 5. Privacy by Default (PII Protection)\n\n### The Challenge\nStudent records contain sensitive personal identifiable information (PII) including guardian mobile numbers, parent emails, and home addresses.\n\n### Protocol\n1. **Opt-In Visibility**:\n   - By default, keep `include_contact_info: false` when calling `get_student_details` or `get_class_roster`.\n2. **Strict Need-to-Know Exposure**:\n   - Never surface `guardian_phone`, `parent_email`, or home addresses in chat responses unless the principal's explicit prompt requested contact details (e.g., *\"Show me Aarav's father's phone number\"* or *\"Send me parent contact sheet for Class 10\"*).\n3. **Settlements & Financial Privacy**:\n   - Bank accounts are automatically masked (e.g., `••••••••1234`). Never attempt to unmask or query raw account numbers.\n\n---\n\n## Quick Tool Reference Matrix\n\n| Tool Name | Type | Key Purpose | Safety / Confirmation Required |\n| :--- | :--- | :--- | :--- |\n| `get_school_overview` | Read | School-level KPI metrics & totals | None (Instant Read) |\n| `get_fee_status` | Read | Live fee collections & overdue balances | None (Instant Read) |\n| `get_attendance_summary`| Read | Attendance percentages & stats | None (Instant Read) |\n| `get_class_roster` | Read | Class student roster & enrollment dates| None (PII hidden by default) |\n| `get_student_details` | Read | Detailed single-student profile | Disambiguate if duplicate names |\n| `get_staff_roster` | Read | Teacher & employee listings | None (Instant Read) |\n| `get_homework_overview` | Read | Class homework review metrics | None (Instant Read) |\n| `get_settlement_status` | Read | Payout batches & masked bank UTRs | None (Read-only) |\n| `get_school_gallery` | Read | School activity media & moments | None (Instant Read) |\n| `create_homework_assignment` | Write | Post new homework assignment | Summarize & Confirm |\n| `update_homework_assignment` | Write | Edit homework instructions/deadline | Summarize & Confirm |\n| `review_homework_submission` | Write | Record submission status & remarks | Summarize & Confirm |\n| `mark_attendance` | Write | Record/overwrite daily attendance | Summarize & Confirm (Highlight diffs)|\n| `add_student` | Write | Register new student & fee plan | Summarize & Confirm |\n| `update_student` | Write | Edit academic profile details | Summarize & Confirm |\n| `bulk_import_students` | Write | Import student batches | **Mandatory Dry-Run Preview First** |\n"
}