pi_mcps/.roo/rules/01-bigmind-core.md

# BigMind Core Rules — Mandatory for All Sessions

## Rule 1: Session Start Ritual (Always First Action — No Exceptions)
Every new session must begin with the following sequence executed in strict order before any other work is performed:
1. `memory_start_session()` — Open a new session and load all prior context, including user preferences, active projects, and recent decisions.
2. `memory_list_hypotheses()` — Review all open hypotheses from previous sessions. Assess whether any have become stale, require updated confidence scores, or can be immediately resolved based on new information.
3. `memory_announce_focus()` — Declare the explicit focus of this session, including the task objective, all files expected to be read or modified, the working branch if applicable, and the IDE environment (ide_hint="VS Code" or ide_hint="IntelliJ" as appropriate). **The focus MUST reflect the current session's task as stated by the user's first message. If the user has not yet given a task at the time of calling, use `"Awaiting user task assignment"` as the description. Never derive focus from a prior session's partial/blocked/abandoned outcome.**
4. `memory_close_stale_sessions()` — Identify and close any orphaned sessions left behind by crashed or terminated IDE instances. A session is considered stale if it has had no activity for more than 2 hours and no corresponding active IDE is detected.

Do not skip any step. Do not reorder. If any call fails, retry once before proceeding with a logged warning.

> **⚠️ CRITICAL — Partial Sessions Are History, Not a Task Queue:**
> Sessions closed with `partial`, `blocked`, or `abandoned` outcomes are **historical records only**.
> They do NOT constitute pending obligations, resumption requests, or open tasks.
> A new session begins fresh. The **only** source of the current session's task is what the user
> writes in their **first message of this conversation** — never the outcome of a prior session.
> Reading prior context is for awareness only — it does NOT authorize beginning any prior task.

## Rule 2: Session End Ritual (Always Last Action — No Exceptions)
Every session must conclude with:
`memory_end_session()` — Close the session with all of the following fields populated:
- **One-liner**: A single sentence summarizing what was accomplished.
- **Topics**: A list of 2-5 topic tags describing the areas touched (e.g., "authentication", "database-migration", "refactor-utils").
- **Outcome**: One of: `completed`, `partial`, `blocked`, `abandoned`, with a brief reason if not completed.
- **Summary**: A 3-8 sentence narrative capturing key decisions made, problems encountered, solutions applied, and any unresolved items carried forward.
- **Importance**: A score from 1-10 reflecting the session's significance to the overall project. Use 7+ for architectural decisions, breaking changes, or critical bug fixes. Use 1-3 for minor exploration or reading-only sessions.

Never allow a session to end implicitly. If the user stops responding or the conversation appears to be ending, proactively initiate the end ritual.

## Rule 3: Search Before Every Task — No Blind Work
Before taking any action on a task, perform a mandatory search of BigMind to avoid redundant work, contradicted decisions, or forgotten context:
- `memory_search_facts(query, limit=10)` — Search for reusable knowledge including user preferences, past decisions, codebase conventions, architectural patterns, and known constraints. Use 2-3 focused keywords that target the specific domain of the task (e.g., "auth token refresh" not "how does authentication work in the project").
- `memory_search_chunks(query, limit=10)` — Search for relevant conversation context from prior sessions including previous discussions, code snippets, debugging sessions, and rationale behind earlier choices.
- **FTS5 AND-match behavior**: Every token in the query must appear in the result. Avoid long queries with rare or highly specific words that reduce match likelihood. If an initial search returns no results, progressively broaden the query by removing the most specific term.
- **Minimum searches per task**: At least one fact search and one chunk search before beginning work. For complex tasks spanning multiple domains, perform searches for each domain independently.
- If search results reveal conflicting information across sessions, flag the conflict explicitly and resolve it before proceeding.

## Rule 4: Store Knowledge Appropriately and Proactively
Capture knowledge in the correct store at the moment it is generated — do not batch or defer:
- `memory_store_fact(category, fact)` — Store atomic, reusable facts the moment they are established. Categories should be consistent and drawn from a controlled vocabulary including but not limited to: `user-preference`, `architecture-decision`, `codebase-convention`, `dependency-info`, `environment-config`, `bug-pattern`, `performance-insight`, `api-contract`, `tool-config`. Each fact must be self-contained and understandable without surrounding context. Avoid vague facts; prefer specificity (e.g., "User prefers Zod over Joi for runtime validation in all TypeScript services" rather than "User likes Zod").
- `memory_append_chunk(session_id, content, role, flag_reason)` — Append conversation exchanges that contain substantive content: decisions with rationale, code implementations, debugging traces, error messages with resolutions, and requirement clarifications. Do not store filler, greetings, or trivial acknowledgments.
- `memory_flag_important(session_id, content, role, flag_reason)` — Proactively flag significant exchanges without waiting to be asked. Flag triggers include: architectural decisions, breaking changes, security-relevant choices, performance trade-offs, user-expressed strong preferences, discovered bugs, deployment-affecting changes, and any "we should remember this" moments. The flag_reason must explain why this exchange matters for future sessions.

## Rule 5: Hypotheses During Analysis — Think Before Acting
Form explicit predictions before undertaking any non-trivial task to create an auditable reasoning trail:
- `memory_add_hypothesis(session_id, hypothesis, confidence=0.7)` — Formulate a testable prediction before investigating a bug, implementing a feature, or making an architectural choice. The hypothesis must be specific and falsifiable (e.g., "The timeout is caused by the connection pool being exhausted under concurrent requests exceeding 50" not "something is wrong with the database"). Set initial confidence between 0.0 and 1.0 based on available evidence: 0.0-0.3 for speculative guesses, 0.4-0.6 for reasoned possibilities, 0.7-0.8 for evidence-backed expectations, 0.9-1.0 for near-certainties.
- `memory_resolve_hypothesis(hypothesis_id, status, resolution)` — Close every hypothesis with what actually happened. Status must be one of: `confirmed` (prediction was correct), `refuted` (prediction was wrong — explain what was actually true), `abandoned` (no longer relevant or testable — explain why). The resolution field must capture the evidence or reasoning that led to the status determination, creating a learning record for future sessions.
- **Mandatory hypothesis points**: Bug investigations (what is the root cause?), performance issues (what is the bottleneck?), refactoring (will this change break existing behavior?), integration work (will these components interact as expected?).
- Review and update confidence scores as new evidence emerges during a session rather than only at resolution time.

## Rule 6: Token Efficiency — Minimize Waste, Maximize Memory Leverage
Actively reduce token consumption by leveraging stored memory and efficient tooling instead of repeatedly reading large files:
- Use `memory_log_token_save(session_id, description, tokens_saved, method_used)` every time you avoid a full file read by using memory recall, CLI tools (grep, awk, sed, tail, head, find), cached knowledge, or targeted partial reads.
- **Calculation**: Estimate tokens_saved ≈ (chars_full / 4) - (chars_result / 4), where chars_full is the estimated character count of the full file or output that would have been consumed, and chars_result is the character count of the actual data retrieved.
- **Preferred methods in order of efficiency**: (1) Memory recall from stored facts or chunks, (2) Targeted CLI commands that extract only relevant lines, (3) Partial file reads with line ranges, (4) Full file reads only when necessary.
- When a file has been read in a previous session and its content is stored in memory, explicitly prefer the memory version and note the token savings. If the file may have changed, verify with a quick checksum or timestamp check before relying on cached content.
- Track cumulative token savings across the session and include the total in the session end summary.

## Rule 7: Parallel Session Awareness and Conflict Prevention
Multiple IDEs and sessions may be active simultaneously. Treat this as a concurrent editing environment:
- Before editing any file, call `memory_get_active_sessions()` to check for other open sessions that may be working on the same files or related modules.
- If a conflict is detected (another session is actively modifying the same file or a tightly coupled dependency), do one of the following: (1) Coordinate by flagging the conflict in both sessions, (2) Defer the edit until the other session completes, or (3) Work on a non-overlapping section with explicit boundaries noted.
- When announcing focus at session start, be specific about file paths so that other sessions can detect potential conflicts accurately.
- If a session discovers that another session has modified a file it depends on, re-read the file and update any cached knowledge before proceeding.
- Log all detected conflicts and their resolutions as facts for future reference using category `session-conflict`.

## Rule 8: Consistency and Self-Correction
- If at any point during a session you realize a rule was skipped or partially followed, immediately remediate by executing the missed step and logging the correction.
- Periodically during long sessions (approximately every 10 substantive exchanges), perform a lightweight self-audit: verify the session is still focused on the announced objective, check for unflagged important exchanges, and update any hypothesis confidence scores that may have shifted.
- If the user provides information that contradicts a stored fact, update the fact immediately and log the change with the old value, new value, and reason for the update.

## Rule 9: Detect and Break Session Loops Before They Start

A **session loop** occurs when multiple consecutive sessions share near-identical headlines, topics,
and `partial`/`blocked`/`abandoned` outcomes — indicating the same task failed to complete repeatedly
without user re-authorization.

**Detection:** If `memory_start_session()` context shows **2 or more** recently closed sessions with:
- Substantially similar headlines or topics, **AND**
- `partial`, `blocked`, or `abandoned` outcome

**Required Response — Break the loop immediately:**
1. Do NOT attempt to resume or retry the repeated task silently
2. Inform the user: "I noticed the last N sessions all attempted [task] and ended partial. I won't auto-resume that. What would you like to do?"
3. Summarize what context/progress was accumulated across those sessions
4. Wait for an explicit user instruction before doing anything

**Explicit resumption:** If the user's first message in this conversation explicitly asks to continue
or retry the previous task, that is a valid instruction — proceed normally. The rule only prevents
**silent autonomous resumption** based on context alone.

**Mode interaction:** This rule applies regardless of mode. Even if a mode's rules say "do the task
immediately," prior session context alone is never sufficient authorization. Only the user's live
message in this conversation authorizes action.