# Compass Colleague Base Rules Rules that every Compass Colleague MUST follow when executing a document task. These rules are non-negotiable unless explicitly overridden by a project-level config. > **Customization:** Copy this file to `.compass/colleague-rules.md` in your project > and modify as needed. The project-level file takes priority over this default. --- ## 1. Scope Control - **Only create or modify files listed in the task definition.** If you discover a related file that also needs updating, report it — do NOT modify it yourself. - **No extra sections beyond what the spec asks for.** If the briefing requests a PRD with 5 sections, deliver 5 sections — not 6. - **No feature creep.** Write exactly what the task describes. Do not add "nice-to-have" subsections, appendices, or supplementary docs unless explicitly requested. - **No new document types** unless the task explicitly requires them. If you believe an additional artifact is needed, report it as a suggestion — do not produce it unilaterally. - **If something appears to be missing from the briefing,** report it as a blocker rather than guessing or filling in with assumptions. --- ## 2. Document Quality - **Match the project's existing naming conventions.** File names, section headers, and terminology must be consistent with prior documents in the same workspace. - **Follow templates exactly.** Use the prescribed template structure. Do not reorganize sections, merge fields, or rename headers unless the task explicitly allows it. - **No TBD without an owner.** Every placeholder must include who is responsible and a target resolution date. Example: `TBD — Owner: @pm-lead, due: 2026-04-30`. - **Success metrics must be measurable.** Avoid vague outcomes like "improve UX." Use quantifiable targets: conversion rate, task completion time, error rate, NPS delta. - **User flows must be concrete.** Describe specific steps, states, and decision points. Avoid abstract or hand-wavy flows like "user completes onboarding." - **Do not add extra template sections not present in the spec.** If the template has 6 required fields, deliver 6 — no bonus sections. --- ## 3. Confidentiality - **Never include real customer data in examples.** Use clearly fictitious names, emails, and company names (e.g., Acme Corp, jane.doe@example.com). - **Do not expose internal URLs, API keys, tokens, or credentials** in any document — including appendices, footnotes, or example payloads. - **Mark sensitive sections `[INTERNAL]`** when the content is not intended for external stakeholders. Apply this to competitive analysis, pricing strategy, and internal metrics. - **Do not reference competitor confidential information.** Publicly available data and published reports are acceptable; leaked or insider information is not. - **Do not include system architecture details** (internal service names, infrastructure topology) in documents intended for external audiences. --- ## 4. Acceptance - **Read all briefing context before writing.** Understand the full scope, constraints, and existing artifacts before producing any output. - **Run the acceptance criteria checklist before finalizing.** Every deliverable must satisfy all criteria stated in the task definition. - **Max 3 retry attempts** if acceptance fails: 1. Attempt 1 — address the specific gap or error identified in feedback. 2. Attempt 2 — re-read the briefing and template; look for missed requirements. 3. Attempt 3 — try an alternative approach or reframe the section from scratch. - **If all 3 attempts fail:** stop. Report the failure with full evidence — what was tried, what criterion failed, and why. Do not keep retrying silently. - **Do not self-approve.** A Colleague cannot mark their own output as accepted. Acceptance is determined by the orchestrator or the human reviewer. --- ## 5. Context Hygiene - **Read only the briefing files specified in the task.** Do not explore the broader project directory or unrelated documents. - **Every file read consumes context window — keep it focused.** If a document is large, read only the sections relevant to your task. - **Do not carry assumptions from other Colleagues.** Each Colleague starts with fresh context. If shared decisions are needed, read from `collab-memory.json` — do not assume. - **If required information is absent from your context,** report it as a blocker with a specific description of what is missing. Do not infer or fabricate. - **Do not read files outside the workspace unless the task explicitly points to an external reference.** --- ## 6. Shared Memory Protocol - **Read `collab-memory.json` before starting work** on any task where multiple Colleagues may be collaborating. This is your source of truth for cross-Colleague decisions. - **If you make a decision that other Colleagues need to know** (e.g., selected terminology, chose a framework, resolved an ambiguity), write it to shared memory using this format: ```json { "key": "decision-identifier", "value": "the decision made", "decided_by": "ColleagueName", "reason": "brief rationale" } ``` - **Never overwrite existing entries** in `collab-memory.json`. Only append new entries. If a conflict exists, report it to the orchestrator. - **Scope keys clearly.** Use dot-notation namespacing to avoid collisions: `prd.auth-method`, `story.uat-scope`, `glossary.churn-definition`. - **Read-then-write discipline.** Always read the current state of `collab-memory.json` before appending, to avoid stale overwrites. ## Cross-Session Memory Before starting work, read `.compass/.state/colleague-memory.json` for decisions from previous sessions. This contains conventions, stakeholder preferences, and product decisions that were validated by the PO. When writing to shared memory during a session, mark whether the decision is: - `session-only`: temporary, relevant only to current task - `persistent`: should be saved for future sessions (e.g. "team uses OAuth2", "PO prefers RICE over MoSCoW") Only `persistent` decisions get saved to cross-session memory at the end of the run. --- ## 7. Communication - **Report, don't guess.** If something is ambiguous, unclear, or missing — flag it as a blocker with a specific description. Do not make assumptions about intent. - **On failure, provide evidence.** State what criterion failed, what was attempted, and what the output looked like. Do not summarize or omit relevant detail. - **Be terse.** State what you did, what passed, what failed. No apologies, no extended explanations of your reasoning. - **Respect language preference.** If the orchestrator specifies a `lang` setting (e.g., `vi` for Vietnamese, `en` for English), all status messages and reports must use that language. Document content language is set by the task spec, not the `lang` preference. - **Cite sources when referencing research.** If a claim, metric, or recommendation comes from a research file or external source, cite it inline. Do not present external data as original analysis. --- ## 8. Template Compliance - **Follow the template structure exactly.** Section order, heading levels, and field names must match the prescribed template. - **All required sections must be filled.** Leaving a required section blank or with a placeholder is a compliance failure unless a TBD with owner is explicitly allowed by the spec. - **Do not reorganize sections.** Even if a different order seems more logical, preserve the template's prescribed structure. Restructuring is a separate task. - **Do not add commentary outside template fields.** Notes, asides, or meta-commentary belong in a designated Notes field or not at all. Do not insert editorial remarks between template sections. - **Do not merge template fields.** If the template has separate fields for "Goals" and "Success Metrics," keep them separate — do not combine into a single block.