@sentry/warden 0.1.0 → 0.2.0

package/.claude/skills/agent-prompt/references/anti-patterns.md

@@ -1,140 +0,0 @@
-# Anti-Patterns
-
-Common mistakes to avoid when writing prompts.
-
-## Over-Emphasis and Anchoring
-
-From [Anthropic's Opus 4.5 guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> Claude Opus 4.5 is more responsive to the system prompt than previous
-> models. Where you might have said "CRITICAL: You MUST...", you can
-> use more normal prompting.
-
-From [Vercel's AGENTS.md research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
-
-> Instructions stating "You MUST invoke the skill" caused agents to anchor
-> excessively on documentation patterns while missing project context.
-
-**Avoid:**
-```markdown
-CRITICAL: You MUST ALWAYS check for SQL injection. NEVER skip this.
-IT IS ABSOLUTELY ESSENTIAL that you...
-```
-
-**Prefer:**
-```markdown
-Understand the code's intent first, then check for SQL injection:
-Is user input concatenated into queries instead of parameterized?
-```
-
-The key insight: "MUST" language causes anchoring on the instruction at the expense of contextual understanding.
-
-## Scope Creep
-
-Each skill should do one thing well.
-
-**Avoid:**
-```markdown
-Find security issues, performance problems, and bugs too.
-```
-
-**Prefer:** Create separate skills for each concern.
-
-## Vague Severity
-
-**Avoid:**
-```markdown
-Use high severity for important issues and medium for less important ones.
-```
-
-**Prefer:**
-```markdown
-- **critical**: Crash, data loss, or silent data corruption
-- **high**: Incorrect behavior in common scenarios
-- **medium**: Incorrect behavior in edge cases
-```
-
-## Negative-Only Instructions
-
-**Avoid:**
-```markdown
-Do not output markdown.
-Do not include explanations.
-Do not wrap in code fences.
-```
-
-**Prefer:**
-```markdown
-Return ONLY valid JSON starting with {"findings":
-```
-
-## Missing Exclusions
-
-Without explicit exclusions, skills report everything tangentially related.
-
-**Avoid:** Omitting "What NOT to Report" section.
-
-**Prefer:**
-```markdown
-## What NOT to Report
-
-- Security vulnerabilities (use security-review skill)
-- Style or formatting issues
-- Performance concerns (unless causing incorrect behavior)
-```
-
-## Hallucination-Prone Patterns
-
-From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> Never speculate about code you have not opened.
-
-**Avoid:** Asking for analysis without providing code context.
-
-**Prefer:** Always include actual code in the prompt (Warden does this automatically).
-
-## Over-Engineering Output
-
-From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> Claude Opus 4.5 has a tendency to overengineer by creating extra files
-> or adding unnecessary abstractions.
-
-For prompts, keep output requirements minimal:
-
-**Avoid:**
-```markdown
-Include a detailed analysis section, then a summary, then recommendations,
-then a risk assessment matrix, then...
-```
-
-**Prefer:**
-```markdown
-Return JSON with findings array. Keep descriptions to 1-2 sentences.
-```
-
-## Conflicting Instructions
-
-**Avoid:**
-```markdown
-Be thorough and check everything.
-...
-Only report high-confidence issues.
-```
-
-**Prefer:** Consistent stance throughout the prompt.
-
-## Missing Examples
-
-For complex output formats, include an example:
-
-**Avoid:** Schema only without example.
-
-**Prefer:**
-```markdown
-Example response format:
-{"findings": [{"id": "sql-injection-1", "severity": "high", ...}]}
-
-Full schema:
-...
-```

package/.claude/skills/agent-prompt/references/context-design.md

@@ -1,124 +0,0 @@
-# Context Design
-
-Research on how context delivery affects agent performance. Based on [Vercel's AGENTS.md evaluation](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals).
-
-## Key Finding: Passive Context Wins
-
-Vercel's evaluation showed dramatic performance differences:
-
-| Approach | Pass Rate |
-|----------|-----------|
-| No docs | 53% |
-| Skills (default) | 53% |
-| Skills with explicit instructions | 79% |
-| AGENTS.md (passive context) | 100% |
-
-## Why Passive Context Outperforms
-
-Three structural advantages:
-
-### 1. Eliminated Decision Burden
-
-Information exists automatically rather than requiring agent judgment about when retrieval is necessary.
-
-**Implication for skills:** Warden injects skill prompts directly into the system prompt. This is passive context - the agent doesn't need to decide to load the skill.
-
-### 2. Persistent Availability
-
-Documentation remains accessible throughout every conversation turn via system prompt.
-
-**Implication for skills:** Keep skill prompts self-contained. Don't require the agent to fetch additional context to understand the task.
-
-### 3. Avoided Sequencing Problems
-
-No competing instructions about whether to explore first vs consult docs first.
-
-**Implication for skills:** Be explicit about the analysis approach. Don't leave ordering ambiguous.
-
-## Instruction Wording Matters
-
-Subtle wording differences produced dramatically divergent outcomes:
-
-| Wording | Effect |
-|---------|--------|
-| "You MUST invoke the skill" | Agent anchored on docs, missed project context |
-| "Explore project first, then invoke skill" | Agent built context first, better results |
-
-### Recommendations
-
-**Avoid:**
-```markdown
-You MUST check for SQL injection on every code change.
-```
-
-**Prefer:**
-```markdown
-Understand the code's intent first, then check for SQL injection:
-Is user input concatenated into queries?
-```
-
-## Retrieval-Led Reasoning
-
-From Vercel's research:
-
-> "Prefer retrieval-led reasoning over pre-training-led reasoning"
-
-This means: look at the actual code before applying general knowledge.
-
-**For Warden skills:**
-```markdown
-## Analysis Approach
-
-1. Read the code context provided
-2. Use Read/Grep to investigate related files if needed
-3. Apply skill criteria to what you've observed
-4. Only report issues you've verified in the code
-```
-
-## Compression Works
-
-Vercel reduced docs from 40KB to 8KB (80% reduction) with no loss in effectiveness.
-
-**Implication for skills:**
-- Concise prompts work as well as verbose ones
-- Use structured formats (tables, lists) over prose
-- Index references rather than including full content
-
-**Example - compressed reference:**
-```markdown
-### Injection Types
-SQL|Command|Template|Header|XSS|Path traversal
-```
-
-vs verbose:
-```markdown
-There are several types of injection vulnerabilities you should check for.
-First, SQL injection occurs when... Second, command injection...
-```
-
-## When Skills Add Value
-
-Skills remain valuable for:
-- User-triggered workflows (version upgrades, migrations)
-- Explicit "apply this standard" requests
-- Tasks requiring specific tool sequences
-
-For general knowledge that should always apply, passive context wins.
-
-## Application to Warden
-
-Warden's architecture aligns with these findings:
-
-1. **Passive injection** - Skill prompts are injected into system prompt
-2. **Hunk context provided** - Code is in the user prompt, not requiring retrieval
-3. **Read-only tools available** - Agent can investigate but starts with context
-
-To maximize effectiveness:
-- Write self-contained skill prompts
-- Include analysis approach (explore → apply criteria)
-- Avoid "MUST" language that causes anchoring
-- Keep prompts concise with structured references
-
-## Sources
-
-- [Vercel: AGENTS.md Outperforms Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)

package/.claude/skills/agent-prompt/references/core-principles.md

@@ -1,75 +0,0 @@
-# Core Principles
-
-Foundational rules for writing effective prompts. Derived from [Anthropic's official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices).
-
-## 1. Be Explicit
-
-Claude 4.x models respond well to clear, explicit instructions.
-
-**Less effective:**
-```
-Review this code for issues.
-```
-
-**More effective:**
-```
-Analyze the code changes for security issues. Only report genuine
-security concerns, not style issues.
-```
-
-## 2. Provide Context and Motivation
-
-Explain *why* a behavior matters.
-
-**Less effective:**
-```
-Never report style issues.
-```
-
-**More effective:**
-```
-Do not report style issues. This skill focuses on security vulnerabilities.
-Style issues are handled by code-simplifier and would create noise here.
-```
-
-## 3. Be Vigilant with Examples
-
-Claude pays close attention to examples. Ensure they demonstrate desired behaviors only.
-
-## 4. Prefer Positive Instructions
-
-Tell Claude what to do, not what to avoid.
-
-**Less effective:**
-```
-Do not use markdown in your response.
-```
-
-**More effective:**
-```
-Return ONLY valid JSON starting with {"findings":
-```
-
-## 5. Scope Narrowly
-
-Broad prompts decrease accuracy. Each skill should have one clear focus.
-
-**Less effective:**
-```
-Find bugs, security issues, performance problems, and style violations.
-```
-
-**More effective:**
-```
-Identify functional bugs that cause incorrect behavior. Focus on null
-handling, off-by-one errors, and async issues.
-```
-
-## 6. Match Prompt Style to Output
-
-The formatting in your prompt influences Claude's response style. Remove markdown from prompts if you want less markdown in output.
-
-## Sources
-
-- [Anthropic: Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
-- [OpenAI: Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)

package/.claude/skills/agent-prompt/references/model-guidance.md

@@ -1,118 +0,0 @@
-# Model-Specific Guidance
-
-Optimizations for Claude 4.x models (Sonnet 4.5, Opus 4.5).
-
-## Claude 4.x Strengths
-
-| Capability | Implication |
-|------------|-------------|
-| Precise instruction following | Can use simpler, more natural prompts |
-| Structured output (JSON) | Reliable parsing without complex extraction |
-| Parallel tool calling | Can investigate multiple files simultaneously |
-| Long-horizon state tracking | Maintains context across extended sessions |
-
-## Prompting Adjustments
-
-### Simpler Language
-
-Claude 4.x doesn't need aggressive emphasis:
-
-**Before (older models):**
-```markdown
-CRITICAL: You MUST use this tool when...
-```
-
-**After (Claude 4.x):**
-```markdown
-Use this tool when...
-```
-
-### More Direct Communication
-
-From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> Claude 4.5 models have a more concise and natural communication style.
-> More direct and grounded, provides fact-based progress rather than
-> self-celebratory updates.
-
-### Explicit Thoroughness
-
-Claude 4.x may be conservative. If you want thorough analysis:
-
-```markdown
-Go beyond the basics to create a fully-featured analysis. Include
-as many relevant findings as possible.
-```
-
-## Thinking and Reflection
-
-Claude 4.x supports thinking between tool calls:
-
-```markdown
-After receiving tool results, carefully reflect on their quality and
-determine optimal next steps before proceeding.
-```
-
-### Interleaved Thinking
-
-For complex multi-step analysis:
-
-```markdown
-Use your thinking to plan and iterate based on new information,
-then take the best next action.
-```
-
-### Thinking Sensitivity
-
-From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> When extended thinking is disabled, Claude Opus 4.5 is particularly
-> sensitive to the word "think" and its variants.
-
-If not using extended thinking, prefer alternatives:
-- "consider" instead of "think about"
-- "evaluate" instead of "think through"
-- "reflect on" instead of "think over"
-
-## Tool Usage
-
-Claude 4.x excels at parallel tool execution:
-
-```markdown
-If you intend to call multiple tools and there are no dependencies,
-make all independent calls in parallel.
-```
-
-### Proactive vs Conservative
-
-To make Claude more proactive:
-
-```markdown
-By default, implement changes rather than only suggesting them.
-Infer the most useful action and proceed.
-```
-
-To make Claude more conservative:
-
-```markdown
-Do not take action unless clearly instructed. Default to providing
-information and recommendations rather than making changes.
-```
-
-## Code Exploration
-
-From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
-
-> Claude Opus 4.5 can be overly conservative when exploring code.
-
-If needed, add explicit instructions:
-
-```markdown
-ALWAYS read and understand relevant files before reporting issues.
-Do not speculate about code you have not inspected.
-```
-
-## Sources
-
-- [Anthropic: Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
-- [Anthropic: What's New in Claude 4.5](https://docs.claude.com/en/about-claude/models/whats-new-claude-4-5)

package/.claude/skills/agent-prompt/references/output-formats.md

@@ -1,98 +0,0 @@
-# Output Formats
-
-How to specify structured output for reliable parsing.
-
-## Enforce JSON-Only Output
-
-Be explicit about format requirements:
-
-```markdown
-IMPORTANT: Your response must be ONLY a valid JSON object.
-No markdown, no explanation, no code fences.
-
-Example response format:
-{"findings": [{"id": "example-1", "severity": "medium", ...}]}
-```
-
-## Provide Complete Schema
-
-Include all available fields so Claude knows the full structure:
-
-```json
-{
-  "findings": [
-    {
-      "id": "unique-identifier",
-      "severity": "critical|high|medium|low|info",
-      "confidence": "high|medium|low",
-      "title": "Short descriptive title",
-      "description": "Detailed explanation",
-      "location": {
-        "path": "path/to/file.ts",
-        "startLine": 10,
-        "endLine": 15
-      },
-      "suggestedFix": {
-        "description": "How to fix",
-        "diff": "unified diff format"
-      }
-    }
-  ]
-}
-```
-
-## Field Requirements
-
-Document which fields are required vs optional:
-
-```markdown
-Requirements:
-- Return ONLY valid JSON starting with {"findings":
-- "findings" array can be empty if no issues found
-- "location.path" is auto-filled - just provide startLine (and optionally endLine). Omit location for general findings.
-- "confidence" reflects certainty given codebase context
-- "suggestedFix" is optional - only include when the fix is complete, correct, and applies to the same file being analyzed. If the fix requires changes to a different file, describe it in the description instead.
-```
-
-## Set Length Expectations
-
-Prevent verbose output:
-
-```markdown
-Keep descriptions SHORT (1-2 sentences max)
-Be concise - focus only on the changes shown
-```
-
-## Empty Results
-
-Explicitly allow empty arrays:
-
-```markdown
-Return an empty findings array if no issues match the skill's criteria:
-{"findings": []}
-```
-
-## Warden's JSON Extraction
-
-The runner handles common output issues (`src/sdk/runner.ts`):
-
-- Strips markdown code fences if present
-- Finds `{"findings"` pattern in prose
-- Extracts balanced JSON with nested objects
-- Validates against FindingSchema with Zod
-
-This provides resilience, but clean JSON output is still preferred.
-
-## Severity Level Definitions
-
-Severity reflects **urgency and required action**, not the type of issue. Each skill defines what "significant impact" means in its domain.
-
-| Level    | Definition                                               |
-|----------|----------------------------------------------------------|
-| critical | Must fix before merge: significant impact if ignored     |
-| high     | Should fix before merge: notable issue affecting quality |
-| medium   | Worth reviewing: potential issue, may need action        |
-| low      | Minor: address when convenient                           |
-| info     | Informational: no action required                        |
-
-Avoid vague definitions like "important" or "less important."

package/.claude/skills/agent-prompt/references/skill-structure.md

@@ -1,115 +0,0 @@
-# Skill Structure
-
-How to write effective Warden skill files.
-
-## File Format
-
-Skills use YAML frontmatter + markdown body:
-
-```markdown
----
-name: skill-name
-description: Brief description for discovery and trigger matching.
-allowed-tools: Read Grep Glob
----
-
-[Prompt body - the actual instructions]
-```
-
-## Required Frontmatter
-
-| Field | Purpose |
-|-------|---------|
-| `name` | Unique identifier, lowercase with hyphens |
-| `description` | One line explaining when to use this skill |
-| `allowed-tools` | Space-separated list (typically `Read Grep Glob`) |
-
-## Recommended Body Structure
-
-```markdown
-[Role statement - who the agent is]
-
-## Your Task
-
-[Clear statement of what to analyze]
-
-### [Category 1]
-
-- Specific pattern to look for
-- Guiding questions: "Is X happening? Does Y exist?"
-
-### [Category 2]
-
-...
-
-## What NOT to Report
-
-[Explicit exclusions prevent scope creep]
-
-## Severity Levels
-
-[Definitions tied to impact]
-
-## Output Requirements
-
-[Formatting expectations]
-```
-
-## Effective Patterns
-
-### Guiding Questions
-
-Help the agent know what to look for:
-
-```markdown
-### Injection Vulnerabilities
-- **SQL injection**: User input concatenated into queries instead of parameterized?
-- **Command injection**: User input passed to shell/exec functions?
-```
-
-### Explicit Exclusions
-
-Prevent false positives and scope creep:
-
-```markdown
-## What NOT to Report
-
-- Security vulnerabilities (use security-review skill)
-- Style or formatting issues
-- Code that "could be better" but works correctly
-```
-
-### Confidence Calibration
-
-Set expectations for certainty:
-
-```markdown
-Do NOT use low or info severity - if you're not confident it's a real
-bug, don't report it.
-```
-
-### Severity Tied to Impact
-
-Avoid vague definitions:
-
-```markdown
-- **critical**: Crash, data loss, or silent data corruption
-- **high**: Incorrect behavior in common scenarios
-- **medium**: Incorrect behavior in edge cases
-```
-
-## File Locations
-
-Skills are discovered in order (first match wins):
-
-1. `.warden/skills/{name}/SKILL.md` - Project-specific
-2. `.agents/skills/{name}/SKILL.md` - Shared agent skills
-3. `.claude/skills/{name}/SKILL.md` - Claude Code skills
-4. `skills/{name}/SKILL.md` - Built-in skills
-
-## Examples
-
-See existing skills for reference:
-- `skills/security-review/SKILL.md` - Comprehensive checklist approach
-- `skills/find-bugs/SKILL.md` - Confidence-focused with exclusions
-- `skills/code-simplifier/SKILL.md` - Balanced "do/don't" guidance