{
  "id": "page:docs-harness-features-backlog-11-prompt-phrasing-analysis",
  "_kind": "Page",
  "_file": "wiki/docs/harness-features-backlog/11-prompt-phrasing-analysis.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/harness-features-backlog/11-prompt-phrasing-analysis.md",
    "sourceKind": "repo-docs",
    "title": "Prompt Phrasing Analysis: CC System Prompts Deep-Dive",
    "displayName": "Prompt Phrasing Analysis: CC System Prompts Deep-Dive",
    "slug": "docs/harness-features-backlog/11-prompt-phrasing-analysis",
    "articlePath": "wiki/docs/harness-features-backlog/11-prompt-phrasing-analysis.md",
    "article": "\n# Prompt Phrasing Analysis: CC System Prompts Deep-Dive\n\n**Category**: Prompt Engineering Intelligence\n**Source**: CC source code -- exact phrasing extracted from Claude Code internals\n\nThis document catalogs specific prompt text, tool descriptions, safety rules, persona instructions, and context assembly patterns from Claude Code that the Babysitter harness should adopt or adapt. Each section includes the exact CC phrasing and a gap assessment against our current prompt generation (`packages/sdk/src/prompts/`).\n\n---\n\n## 1. System Prompt Architecture\n\n### CC Prompt Assembly Order\n\nCC builds its system prompt in a strict priority hierarchy (`src/utils/systemPrompt.ts`):\n\n1. **Override** (replaces everything if set)\n2. **Coordinator** (replaces default entirely in coordinator mode)\n3. **Agent** (replaces default in normal mode; appends in proactive mode)\n4. **Custom** (user-supplied `appendSystemPrompt`)\n5. **Default** (the standard prompt from `src/constants/prompts.ts`)\n\n**Gap**: Our `PromptContext` + per-harness context factories compose prompts but have no equivalent priority hierarchy. All sections are concatenated without precedence rules.\n\n**Actionable**: Implement a prompt priority model in `packages/sdk/src/prompts/` where overlay prompts (process-specific, phase-specific, mode-specific) have clear precedence over defaults.\n\n### CC Prompt Sections (in order)\n\nThe default system prompt is assembled from these sections:\n\n1. **Identity**: `\"You are Claude Code, Anthropic's official CLI for Claude.\"`\n2. **Simple Intro**: `\"You are an interactive agent that helps users with software engineering tasks.\"`\n3. **System section**: Tool output visibility, permission modes, auto-compression, system-reminder tags, prompt injection detection\n4. **Doing Tasks**: Coding philosophy (don't over-engineer, don't add features beyond what was asked)\n5. **Cyber Risk**: Security testing boundaries\n6. **Executing Actions with Care**: Reversibility and blast radius assessment\n7. **Using Your Tools**: Tool preference rules (dedicated tools over Bash)\n8. **Tone and Style**: Emoji policy, conciseness, code references\n9. **Output Efficiency**: Brevity rules\n10. **Environment**: Platform, shell, git status, model info\n\n**Gap**: Our `instructions:babysit-skill` generates orchestration-focused prompts but does not include equivalent coding philosophy, tool preference rules, or output efficiency instructions. The delegated harness (CC) brings its own, but when using Pi or other harnesses, these are missing.\n\n---\n\n## 2. Coding Philosophy Instructions (High Priority)\n\n### \"Doing Tasks\" Section -- Exact Phrasing\n\nThese instructions from `src/constants/prompts.ts` are highly effective at preventing common AI coding mistakes:\n\n> \"Don't add features, refactor code, or make 'improvements' beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.\"\n\n> \"Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.\"\n\n> \"Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is what the task actually requires -- no speculative abstractions, but no half-finished implementations either. Three similar lines of code is better than a premature abstraction.\"\n\n> \"Avoid backwards-compatibility hacks like renaming unused _vars, re-exporting types, adding // removed comments for removed code, etc. If you are certain that something is unused, you can delete it completely.\"\n\n> \"If an approach fails, diagnose why before switching tactics -- read the error, check your assumptions, try a focused fix. Don't retry the identical action blindly, but don't abandon a viable approach after a single failure either.\"\n\n**Gap**: Our process prompts and `instructions:*` output do not include any equivalent coding philosophy. When orchestrating tasks via non-CC harnesses (Pi, Gemini, Codex), the delegated agent lacks these guardrails.\n\n**Recommendation**: Add a `codingPhilosophy` prompt section to `packages/sdk/src/prompts/` that is injected into task prompts for code-writing tasks.\n\n---\n\n## 3. Tool Preference Rules (High Priority)\n\n### \"Using Your Tools\" Section -- Exact Phrasing\n\nCC has explicit rules preventing Bash misuse:\n\n> \"Do NOT use the Bash to run commands when a relevant dedicated tool is provided. Using dedicated tools allows the user to better understand and review your work. This is CRITICAL to assisting the user:\n> - To read files use Read instead of cat, head, tail, or sed\n> - To edit files use Edit instead of sed or awk\n> - To create files use Write instead of cat with heredoc or echo redirection\n> - To search for files use Glob instead of find or ls\n> - To search the content of files, use Grep instead of grep or rg\n> - Reserve using the Bash exclusively for system commands and terminal operations that require shell execution.\"\n\n**Gap**: Our agentic tool definitions (`packages/sdk/src/harness/agenticTools.ts`) define tools but do not include meta-instructions about when to prefer which tool. When Pi sessions use our agentic tools, the agent lacks guidance on tool selection.\n\n**Recommendation**: Add tool preference instructions to the agentic tools system prompt preamble.\n\n---\n\n## 4. Safety & Security Instructions (High Priority)\n\n### Cyber Risk Instruction -- Exact Phrasing\n\nFrom `src/constants/cyberRiskInstruction.ts`:\n\n> \"IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes. Dual-use security tools (C2 frameworks, credential testing, exploit development) require clear authorization context: pentesting engagements, CTF competitions, security research, or defensive use cases.\"\n\n### Careful Reversibility -- Exact Phrasing\n\nFrom `src/constants/prompts.ts` (Actions section):\n\n> \"Carefully consider the reversibility and blast radius of actions. Generally you can freely take local, reversible actions like editing files or running tests. But for actions that are hard to reverse, affect shared systems beyond your local environment, or could otherwise be risky or destructive, check with the user before proceeding.\"\n\nSpecific examples listed:\n- **Destructive operations**: deleting files/branches, dropping database tables, killing processes, rm -rf\n- **Hard-to-reverse operations**: force-pushing, git reset --hard, amending published commits\n- **Actions visible to others**: pushing code, creating/closing PRs/issues, sending messages\n- **Third-party uploads**: consider sensitivity before sending to external tools\n\n**Gap**: Our breakpoint system (`packages/sdk/src/breakpoints/`) gates on user approval but process prompts do not include equivalent reversibility reasoning. The delegated agent is not instructed to think about blast radius before acting.\n\n**Recommendation**: Add a `safetyGuidelines` prompt section for task prompts that includes both the cyber risk boundary and the reversibility framework.\n\n---\n\n## 5. Output Efficiency Rules (Medium Priority)\n\n### Exact Phrasing\n\n> \"IMPORTANT: Go straight to the point. Try the simplest approach first without going in circles. Do not overdo it. Be extra concise.\"\n\n> \"Keep your text output brief and direct. Lead with the answer or action, not the reasoning. Skip filler words, preamble, and unnecessary transitions. Do not restate what the user said -- just do it.\"\n\n> \"Focus text output on:\n> - Decisions that need the user's input\n> - High-level status updates at natural milestones\n> - Errors or blockers that change the plan\"\n\n> \"If you can say it in one sentence, don't use three.\"\n\n**Gap**: Our iteration prompts do not include output efficiency guidelines. Delegated agents often produce verbose output that consumes token budget unnecessarily.\n\n**Recommendation**: Include output efficiency rules in the `session:iteration-message` prompt template.\n\n---\n\n## 6. Git Operations Protocol (Medium Priority)\n\n### Commit Protocol -- Exact Phrasing\n\nCC has a detailed, step-by-step commit protocol:\n\n> \"1. Run git status, git diff, git log in parallel\n> 2. Analyze all staged changes and draft a commit message: Summarize the nature of the changes. Do not commit files that likely contain secrets (.env, credentials.json, etc).\n> 3. Add relevant untracked files, create the commit, run git status after.\n> 4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit.\"\n\nCritical rules:\n> \"NEVER update the git config\"\n> \"NEVER run destructive git commands (push --force, reset --hard) unless the user explicitly requests\"\n> \"NEVER skip hooks (--no-verify, --no-gpg-sign) unless the user explicitly requests\"\n> \"CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests\"\n\n**Gap**: Our process prompts do not include git safety protocols. When orchestrated tasks involve git operations, the delegated agent lacks these guardrails.\n\n**Recommendation**: Add a `gitSafety` prompt section injected when tasks involve code changes or version control.\n\n---\n\n## 7. Tool Descriptions -- Key Patterns (Medium Priority)\n\n### Pattern: Read-Before-Edit Enforcement\n\nMultiple CC tools enforce a read-before-write pattern:\n\n**FileEditTool**: `\"You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.\"`\n\n**FileWriteTool**: `\"If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\"`\n\n**Gap**: Our agentic tools do not enforce read-before-write. Agents can blindly overwrite files.\n\n### Pattern: Dedicated Tool Preference\n\n**GrepTool**: `\"ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command. The Grep tool has been optimized for correct permissions and access.\"`\n\n**GlobTool**: `\"When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead\"`\n\n### Pattern: Agent Tool Briefing Style\n\n**AgentTool**: `\"Brief the agent like a smart colleague who just walked into the room -- it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.\"`\n\n> \"Never delegate understanding. Don't write 'based on your findings, fix the bug' or 'based on the research, implement it.' Those phrases push synthesis onto the agent instead of doing it yourself.\"\n\n**Gap**: These patterns are not replicated in our agentic tool definitions. The tools work but lack the behavioral guardrails.\n\n---\n\n## 8. Compaction Protocol (High Priority)\n\n### Structure -- Exact Sections\n\nCC's compaction prompt (`src/services/compact/prompt.ts`) produces a summary with these mandatory sections:\n\n1. **Primary Request and Intent** (detailed)\n2. **Key Technical Concepts** (list)\n3. **Files and Code Sections** (with why important, code snippets)\n4. **Errors and Fixes**\n5. **Problem Solving** (approaches tried)\n6. **All User Messages** (non-tool-result, verbatim or near-verbatim)\n7. **Pending Tasks**\n8. **Current Work** (precise description of where things stand)\n9. **Optional Next Step** (with quotes from recent conversation)\n\nKey rules:\n> \"CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.\"\n> Uses `<analysis>` block as drafting scratchpad (stripped before reaching context) + `<summary>` block for final output.\n\n**Gap**: Our compression module (`packages/sdk/src/compression/`) does token-level dedup but not conversation-level compaction. When orchestrating long runs, we rely on the host harness for compaction. For Pi and other non-CC harnesses, there is no equivalent.\n\n**Recommendation**: Implement a compaction prompt template in `packages/sdk/src/prompts/` that can be used to generate summary prompts for long-running orchestrations.\n\n---\n\n## 9. Memory Extraction Patterns (Medium Priority)\n\n### Four-Type Memory Taxonomy\n\nCC uses a structured memory system with four types:\n\n1. **user**: Role, goals, preferences, knowledge (`\"Great user memories help you tailor future behavior\"`)\n2. **feedback**: Corrections and confirmations (`\"Record from failure AND success\"`)\n3. **project**: Ongoing work context (`\"Always convert relative dates to absolute dates\"`)\n4. **reference**: Pointers to external systems (`\"Where to find up-to-date information\"`)\n\n### Memory File Format\n```markdown\n---\nname: {{memory name}}\ndescription: {{one-line description}}\ntype: {{user, feedback, project, reference}}\n---\n{{memory content}}\n```\n\nIndexed in `MEMORY.md`: `- [Title](file.md) -- one-line hook` (<150 chars per entry)\n\n**Gap**: Our profile system (`packages/sdk/src/profiles/`) stores user and project profiles but does not have the four-type taxonomy or the feedback/reference memory types. Our system does not extract and persist insights across runs.\n\n---\n\n## 10. Proactive/Autonomous Mode Instructions (Low Priority -- Future)\n\n### Autonomous Agent Behavior\n\nCC's proactive mode has detailed behavioral instructions:\n\n> \"You are running autonomously. You will receive `<tick>` prompts that keep you alive between turns.\"\n\nKey behaviors:\n- **Bias toward action**: `\"Act on best judgment, not asking confirmation\"`\n- **Terminal focus calibration**: Unfocused (user away) = lean autonomous; Focused (user watching) = collaborate\n- **Pacing**: Must call SLEEP if nothing useful to do\n- **First wake-up**: Greet briefly and ask what to work on\n- **Subsequent wake-ups**: Look for useful work, don't spam questions\n\n### Brief Tool Protocol\n\n> \"Every user message gets a reply through Brief\"\n> \"If need to investigate: ack first ('On it -- checking...'), then work, then result\"\n\n**Gap**: Our harness does not have an autonomous/proactive mode. Runs are explicitly triggered. This is aspirational but worth tracking for future platform capabilities.\n\n---\n\n## 11. Environment Context Assembly (Medium Priority)\n\n### What CC Injects as Environment Context\n\nCC injects the following runtime context into every prompt:\n\n- Working directory (CWD)\n- Is git repo: Yes/No\n- Additional working directories\n- Platform (win32, darwin, linux)\n- Shell (bash/zsh with syntax note: \"use Unix shell syntax, not Windows\")\n- OS Version\n- Model name/ID with knowledge cutoff date\n- Git worktree status (if applicable)\n- Current date\n\n**Gap**: Our `session:iteration-message` includes run context (run ID, iteration count, pending effects) but does not include platform, shell, git status, or model identity. When the delegated agent is Pi or another non-CC harness, it lacks this environmental awareness.\n\n**Recommendation**: Enrich the iteration prompt with environment context from `packages/sdk/src/config/` and runtime detection.\n\n---\n\n## Summary: Priority Adoption Matrix\n\n| # | Pattern | Priority | Effort | Impact |\n|---|---------|----------|--------|--------|\n| 1 | Coding Philosophy Instructions | High | S | Prevents over-engineering in non-CC harnesses |\n| 2 | Tool Preference Rules | High | S | Reduces token waste from Bash misuse |\n| 3 | Safety/Reversibility Framework | High | S | Prevents destructive actions in orchestrated tasks |\n| 4 | Compaction Protocol | High | M | Enables long-running orchestrations |\n| 5 | Output Efficiency Rules | Medium | S | Reduces token consumption |\n| 6 | Git Operations Protocol | Medium | S | Prevents git mishaps in code tasks |\n| 7 | Read-Before-Edit Enforcement | Medium | S | Prevents blind file overwrites |\n| 8 | Agent Briefing Style | Medium | S | Improves delegated task quality |\n| 9 | Environment Context Assembly | Medium | M | Platform-aware orchestration |\n| 10 | Memory Taxonomy | Medium | L | Cross-run learning |\n| 11 | Proactive Mode | Low | XL | Autonomous orchestration (future) |\n| 12 | Prompt Priority Hierarchy | Medium | M | Composable prompt overlays |\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-harness-features-backlog",
      "to": "page:docs-harness-features-backlog-11-prompt-phrasing-analysis",
      "kind": "contains_page"
    }
  ]
}