@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/skills/workflow/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: workflow
+description: Create, run, inspect, and improve pi/atomic workflows. Use whenever the user wants a reusable multi-stage automation, DAG or staged agent pipeline, workflow definition, defineWorkflow file, ctx.task/ctx.parallel/ctx.chain/ctx.stage orchestration, /workflow run/status/resume help, custom workflow discovery, or context-engineered multi-session process.
+---
+
+# Workflow Skill
+
+You help users create and operate pi/atomic workflows. A workflow is a reusable TypeScript definition that orchestrates named stages, parallel branches, handoffs, artifacts, user-input prompts, status UI, and resumable runs through pi's workflow extension.
+
+This skill is for people using workflows. Default to helping users author workflow definitions and run them through pi. Only discuss package implementation details if the user explicitly asks to modify the `@bastani/workflows` package itself.
+
+Use this skill for two user journeys:
+
+1. **Run or inspect an existing workflow** — use the workflow tool or `/workflow` surface. Load `references/running-workflows.md`.
+2. **Create or edit a workflow definition** — design the information flow, then author a `defineWorkflow(...).run(...).compile()` TypeScript file. Load `references/sdk-authoring.md` and `references/design-checklist.md`.
+
+## Reference Files
+
+Load references on demand. Keep this file lean; put details in references.
+
+| File | Load when |
+| --- | --- |
+| `references/sdk-authoring.md` | Creating/editing workflow definition files, inputs, `ctx.task`, `ctx.parallel`, `ctx.chain`, `ctx.stage`, or programmatic runner usage. |
+| `references/running-workflows.md` | Running, monitoring, interrupting, resuming, or inspecting workflows. |
+| `references/design-checklist.md` | Before implementing or shipping any non-trivial workflow. |
+| `references/context-engineering.md` | Any multi-stage or multi-agent workflow; routes to copied context-engineering references. |
+| `references/context-engineering/context-fundamentals.md` | Prompt/context basics, token budgeting, prompt placement, progressive disclosure. |
+| `references/context-engineering/context-degradation.md` | Long conversations, loops, accumulated state, context loss. |
+| `references/context-engineering/context-compression.md` | Summarizing/compressing transcripts or large research bundles. |
+| `references/context-engineering/context-optimization.md` | Token/cost optimization, cache-friendly ordering, large fan-outs. |
+| `references/context-engineering/multi-agent-patterns.md` | Orchestrator/specialist/reviewer topologies and handoff protocols. |
+| `references/context-engineering/filesystem-context.md` | File/artifact-based coordination between stages. |
+| `references/context-engineering/evaluation.md` | Quality gates, success criteria, deterministic evaluation. |
+| `references/context-engineering/advanced-evaluation.md` | LLM-as-judge review/evaluator stages. |
+| `references/context-engineering/tool-design.md` | Custom tools, MCP/tool scope design, stage capabilities. |
+| `references/context-engineering/memory-systems.md` | Cross-run memory or durable project knowledge. |
+| `references/context-engineering/hosted-agents.md` | Remote/containerized/hosted execution environments. |
+| `references/context-engineering/project-development.md` | Decide whether a task is viable for agent workflow automation. |
+| `references/context-engineering/bdi-mental-states.md` | Formal deliberative/cognitive decomposition workflows. |
+
+## First Decision: Running vs Authoring
+
+Classify the user's ask before acting:
+
+- **Run**: "run workflow X", "kick off ralph", "is it done?", "resume", "interrupt", "status", "what inputs does it need?" → load `references/running-workflows.md`; list/inspect first if needed; execute rather than merely printing commands when tools allow.
+- **Author**: "create a workflow", "turn this process into a workflow", "add a stage", "make a reusable workflow", "defineWorkflow", "ctx.parallel", "workflow schema" → load `references/sdk-authoring.md`; design before coding.
+- **Design/architecture**: "make this workflow robust", "multi-agent pipeline", "context handoff", "review/fix loop" → load `references/design-checklist.md` and `references/context-engineering.md` before writing code.
+
+## Running Existing Workflows
+
+Inspect before running unfamiliar named workflows:
+
+```ts
+workflow({ action: "list" })
+workflow({ action: "inputs", workflow: "deep-research-codebase" })
+workflow({ workflow: "deep-research-codebase", inputs: { prompt: "map workflow runtime" } })
+```
+
+Slash equivalents:
+
+```text
+/workflow list
+/workflow inputs deep-research-codebase
+/workflow deep-research-codebase prompt="map src" max_partitions=2
+/workflow status --all
+/workflow status <run-id>
+/workflow resume <run-id>
+```
+
+Named workflow dispatch is background-oriented: expect a run id and then monitor status/attention states.
+
+## Direct Workflow-Native Orchestration
+
+Use direct workflow calls when the current task needs workflow tracking but not a pre-authored reusable definition.
+
+Single tracked task:
+
+```ts
+workflow({
+  task: {
+    name: "reviewer",
+    task: "Review the auth module and summarize risks.",
+    context: "fresh",
+    output: "reviews/auth.md"
+  }
+})
+```
+
+Parallel fan-out:
+
+```ts
+workflow({
+  tasks: [
+    { name: "api-reviewer", task: "Review API surfaces" },
+    { name: "runtime-reviewer", task: "Review runtime behavior" }
+  ],
+  concurrency: 2,
+  async: true,
+  outputMode: "file-only"
+})
+```
+
+Dependent chain:
+
+```ts
+workflow({
+  task: "map the release process",
+  chain: [
+    { name: "researcher", task: "Research {task}" },
+    {
+      parallel: [
+        { name: "risk-reviewer", task: "Review risks in {previous}" },
+        { name: "docs-reviewer", task: "Find documentation gaps in {previous}" }
+      ],
+      concurrency: 2
+    },
+    { name: "planner", task: "Create a plan from {previous}" }
+  ],
+  async: true,
+  intercom: { delivery: "result" }
+})
+```
+
+Task options mirror pi session options plus workflow-owned fields such as `output`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `model`, `fallbackModels`, `thinkingLevel`, and per-stage `mcp` allow/deny.
+
+## Authoring Process
+
+### 1. Locate the workflow surface
+
+For user-authored workflows, place definitions where pi discovers them:
+
+- Project-local: `.atomic/workflows/*.ts` inside the current project.
+- User-global: `~/.atomic/agent/workflows/*.ts` for workflows available across projects.
+- Package workflows: a pi package can expose bundled workflow directories through `package.json` under `pi.builtin`.
+
+If an existing project has workflow examples, inspect those first for import style and naming conventions. In a normal consumer project, import from the package:
+
+```ts
+import { defineWorkflow } from "@bastani/workflows";
+```
+
+When editing this repository's own fixtures or bundled examples, follow the local import style already used by nearby workflow files.
+
+### 2. Design the workflow before coding
+
+For non-trivial workflows, complete the design checklist. A workflow is an information-flow system, not a list of prompts. Identify:
+
+- goal and non-goals
+- input schema
+- stage decomposition: one LLM conversation per stage
+- sequential vs parallel vs conditional control flow
+- context handoff mechanism for every edge
+- deterministic computation outside stages
+- output artifacts and structured final return
+- model/tool/MCP/session requirements
+- failure modes and quality gates
+
+Load context-engineering references that match the topology. For example, load `multi-agent-patterns.md` for specialist fan-out, `context-compression.md` for transcript handoffs, and `evaluation.md` for review gates.
+
+### 3. Implement the workflow definition
+
+Canonical shape:
+
+```ts
+import { defineWorkflow } from "@bastani/workflows";
+
+export default defineWorkflow("explain-file")
+  .description("Explain a file with tracked workflow stages.")
+  .input("path", { type: "text", required: true, description: "File path to explain." })
+  .run(async (ctx) => {
+    const explanation = await ctx.task("explain", {
+      task: `Read ${ctx.inputs.path} and explain purpose, risks, and key symbols.`,
+      context: "fresh",
+    });
+
+    return { explanation: explanation.text };
+  })
+  .compile();
+```
+
+Builder rules:
+
+- `defineWorkflow("name")` starts a builder; name must be non-empty.
+- `.description(text)` sets listing text.
+- `.input(key, schema)` declares typed inputs.
+- `.run(async (ctx) => ({ ... }))` defines the workflow body.
+- `.compile()` returns the workflow definition for discovery.
+
+Input types: `text`, `string`, `number`, `boolean`, `select`. All support `description` and `required`; defaults are type-specific; `select` requires `choices`.
+
+### 4. Pick the right primitive
+
+| Need | Use |
+| --- | --- |
+| One LLM task with workflow tracking | `ctx.task(name, options)` |
+| Independent branches | `ctx.parallel(steps, { task? })` |
+| Dependent stages | `ctx.chain(steps, { task? })` |
+| Low-level session controls | `ctx.stage(name, options)` then `stage.prompt/complete` |
+| User interaction during run | `ctx.ui` primitives |
+| Pure computation / file I/O / parsing | Plain TypeScript in `.run()` or helpers |
+
+Use `previous` plus `{previous}` for context handoff. If no placeholder is present, the runtime appends context. Chain defaults: first missing task uses `{task}`, later missing tasks use `{previous}`, and missing tasks inside chain-parallel groups use `{previous}`.
+
+### 5. Engineer context explicitly
+
+For every stage boundary answer:
+
+- What exact information does the downstream stage need?
+- Is text handoff enough, or should data be structured or file-backed?
+- How large can this context get?
+- Should it be summarized/compressed first?
+- What evidence must be cited by path, symbol, command, or artifact?
+- What happens if a branch fails, produces low-confidence output, or needs user input?
+
+Prefer concise structured returns and durable artifacts over dumping full transcripts into downstream prompts. Use filesystem/artifact handoffs for large outputs and evaluator stages for quality-sensitive work.
+
+## Execution Model
+
+`@bastani/workflows` follows pi's package/extension model: pi loads the extension from the package manifest, and the extension registers the `workflow` tool, `/workflow` command, UI renderers, widgets, and lifecycle hooks in-process.
+
+Use these supported workflow surfaces:
+
+- `/workflow <name> key=value ...` for interactive pi use.
+- The `workflow` tool for LLM-initiated orchestration.
+- `runWorkflow(definition)` for explicit library/script usage.
+
+Programmatic runner example:
+
+```ts
+import { runWorkflow, type WorkflowOptions } from "@bastani/workflows";
+
+const definition = {
+  mode: "workflow",
+  workflow: "deep-research-codebase",
+  inputs: {
+    prompt: "map workflow sdk",
+    max_partitions: 1,
+  },
+} as const;
+
+const options: WorkflowOptions = {};
+
+await runWorkflow(definition, options);
+```
+
+## Safety and Compatibility Rules
+
+- Do not fabricate workflow names or inputs; list/inspect first.
+- Do not use legacy workflow tool fields such as `agent`, `stage`, or run-control `name`.
+- Do not expect workflow-tool `create`, `update`, or `delete`; reusable definitions are code-authored.
+- Use `/workflow` slash commands for named runs, inspection, status, and diagnostics.
+- Prefer `ctx.task`, `ctx.parallel`, and `ctx.chain`; drop to `ctx.stage` only for lower-level controls.
+- Keep stage names user-readable because they appear in workflow status/UI.
+- Put deterministic code outside standalone stages.
+- Return compact structured output and save large artifacts to files.

package/dist/builtin/workflows/skills/workflow/references/context-engineering/advanced-evaluation.md

@@ -0,0 +1,404 @@
+---
+name: advanced-evaluation
+description: This skill should be used when the user asks to "implement LLM-as-judge", "compare model outputs", "create evaluation rubrics", "mitigate evaluation bias", or mentions direct scoring, pairwise comparison, position bias, evaluation pipelines, or automated quality assessment. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of evaluating LLM output quality.
+metadata:
+  provider: atomic
+---
+
+# Advanced Evaluation
+
+This skill covers production-grade techniques for evaluating LLM outputs using LLMs as judges. It synthesizes research from academic papers, industry practices, and practical implementation experience into actionable patterns for building reliable evaluation systems.
+
+**Key insight**: LLM-as-a-Judge is not a single technique but a family of approaches, each suited to different evaluation contexts. Choosing the right approach and mitigating known biases is the core competency this skill develops.
+
+## When to Activate
+
+Activate this skill when:
+
+- Building automated evaluation pipelines for LLM outputs
+- Comparing multiple model responses to select the best one
+- Establishing consistent quality standards across evaluation teams
+- Debugging evaluation systems that show inconsistent results
+- Designing A/B tests for prompt or model changes
+- Creating rubrics for human or automated evaluation
+- Analyzing correlation between automated and human judgments
+
+## Core Concepts
+
+### The Evaluation Taxonomy
+
+Select between two primary approaches based on whether ground truth exists:
+
+**Direct Scoring** — Use when objective criteria exist (factual accuracy, instruction following, toxicity). A single LLM rates one response on a defined scale. Achieves moderate-to-high reliability for well-defined criteria. Watch for score calibration drift and inconsistent scale interpretation.
+
+**Pairwise Comparison** — Use for subjective preferences (tone, style, persuasiveness). An LLM compares two responses and selects the better one. Achieves higher human-judge agreement than direct scoring for preference tasks (Zheng et al., 2023). Watch for position bias and length bias.
+
+### The Bias Landscape
+
+Mitigate these systematic biases in every evaluation system:
+
+**Position Bias**: First-position responses get preferential treatment. Mitigate by evaluating twice with swapped positions, then apply majority vote or consistency check.
+
+**Length Bias**: Longer responses score higher regardless of quality. Mitigate by explicitly prompting to ignore length and applying length-normalized scoring.
+
+**Self-Enhancement Bias**: Models rate their own outputs higher. Mitigate by using different models for generation and evaluation.
+
+**Verbosity Bias**: Excessive detail scores higher even when unnecessary. Mitigate with criteria-specific rubrics that penalize irrelevant detail.
+
+**Authority Bias**: Confident tone scores higher regardless of accuracy. Mitigate by requiring evidence citation and adding a fact-checking layer.
+
+### Metric Selection Framework
+
+Match metrics to the evaluation task structure:
+
+| Task Type | Primary Metrics | Secondary Metrics |
+|-----------|-----------------|-------------------|
+| Binary classification (pass/fail) | Recall, Precision, F1 | Cohen's kappa |
+| Ordinal scale (1-5 rating) | Spearman's rho, Kendall's tau | Cohen's kappa (weighted) |
+| Pairwise preference | Agreement rate, Position consistency | Confidence calibration |
+| Multi-label | Macro-F1, Micro-F1 | Per-label precision/recall |
+
+Prioritize systematic disagreement patterns over absolute agreement rates because a judge that consistently disagrees with humans on specific criteria is more problematic than one with random noise.
+
+## Evaluation Approaches
+
+### Direct Scoring Implementation
+
+Build direct scoring with three components: clear criteria, a calibrated scale, and structured output format.
+
+**Criteria Definition Pattern**:
+```
+Criterion: [Name]
+Description: [What this criterion measures]
+Weight: [Relative importance, 0-1]
+```
+
+**Scale Calibration** — Choose scale granularity based on rubric detail:
+- 1-3: Binary with neutral option, lowest cognitive load
+- 1-5: Standard Likert, best balance of granularity and reliability
+- 1-10: Use only with detailed per-level rubrics because calibration is harder
+
+**Prompt Structure for Direct Scoring**:
+```
+You are an expert evaluator assessing response quality.
+
+## Task
+Evaluate the following response against each criterion.
+
+## Original Prompt
+{prompt}
+
+## Response to Evaluate
+{response}
+
+## Criteria
+{for each criterion: name, description, weight}
+
+## Instructions
+For each criterion:
+1. Find specific evidence in the response
+2. Score according to the rubric (1-{max} scale)
+3. Justify your score with evidence
+4. Suggest one specific improvement
+
+## Output Format
+Respond with structured JSON containing scores, justifications, and summary.
+```
+
+Always require justification before the score in all scoring prompts because research shows this improves reliability by 15-25% compared to score-first approaches.
+
+### Pairwise Comparison Implementation
+
+Apply position bias mitigation in every pairwise evaluation:
+
+1. First pass: Response A in first position, Response B in second
+2. Second pass: Response B in first position, Response A in second
+3. Consistency check: If passes disagree, return TIE with reduced confidence
+4. Final verdict: Consistent winner with averaged confidence
+
+**Prompt Structure for Pairwise Comparison**:
+```
+You are an expert evaluator comparing two AI responses.
+
+## Critical Instructions
+- Do NOT prefer responses because they are longer
+- Do NOT prefer responses based on position (first vs second)
+- Focus ONLY on quality according to the specified criteria
+- Ties are acceptable when responses are genuinely equivalent
+
+## Original Prompt
+{prompt}
+
+## Response A
+{response_a}
+
+## Response B
+{response_b}
+
+## Comparison Criteria
+{criteria list}
+
+## Instructions
+1. Analyze each response independently first
+2. Compare them on each criterion
+3. Determine overall winner with confidence level
+
+## Output Format
+JSON with per-criterion comparison, overall winner, confidence (0-1), and reasoning.
+```
+
+**Confidence Calibration** — Map confidence to position consistency:
+- Both passes agree: confidence = average of individual confidences
+- Passes disagree: confidence = 0.5, verdict = TIE
+
+### Rubric Generation
+
+Generate rubrics to reduce evaluation variance by 40-60% compared to open-ended scoring.
+
+**Include these rubric components**:
+1. **Level descriptions**: Clear boundaries for each score level
+2. **Characteristics**: Observable features that define each level
+3. **Examples**: Representative text for each level (optional but valuable)
+4. **Edge cases**: Guidance for ambiguous situations
+5. **Scoring guidelines**: General principles for consistent application
+
+**Set strictness calibration** for the use case:
+- **Lenient**: Lower passing bar, appropriate for encouraging iteration
+- **Balanced**: Typical production expectations
+- **Strict**: High standards for safety-critical or high-stakes evaluation
+
+Adapt rubrics to the domain — use domain-specific terminology. A code readability rubric mentions variables, functions, and comments. A medical accuracy rubric references clinical terminology and evidence standards.
+
+## Practical Guidance
+
+### Evaluation Pipeline Design
+
+Build production evaluation systems with these layers: Criteria Loader (rubrics + weights) -> Primary Scorer (direct or pairwise) -> Bias Mitigation (position swap, etc.) -> Confidence Scoring (calibration) -> Output (scores + justifications + confidence). See [Evaluation Pipeline Diagram](./references/evaluation-pipeline.md) for the full visual layout.
+
+### Decision Framework: Direct vs. Pairwise
+
+Apply this decision tree:
+
+```
+Is there an objective ground truth?
++-- Yes -> Direct Scoring
+|   Examples: factual accuracy, instruction following, format compliance
+|
++-- No -> Is it a preference or quality judgment?
+    +-- Yes -> Pairwise Comparison
+    |   Examples: tone, style, persuasiveness, creativity
+    |
+    +-- No -> Consider reference-based evaluation
+        Examples: summarization (compare to source), translation (compare to reference)
+```
+
+### Scaling Evaluation
+
+For high-volume evaluation, apply one of these strategies:
+
+1. **Panel of LLMs (PoLL)**: Use multiple models as judges and aggregate votes to reduce individual model bias. More expensive but more reliable for high-stakes decisions.
+
+2. **Hierarchical evaluation**: Use a fast cheap model for screening and an expensive model for edge cases. Requires calibration of the screening threshold.
+
+3. **Human-in-the-loop**: Automate clear cases and route low-confidence decisions to human review. Design feedback loops to improve automated evaluation over time.
+
+## Examples
+
+### Example 1: Direct Scoring for Accuracy
+
+**Input**:
+```
+Prompt: "What causes seasons on Earth?"
+Response: "Seasons are caused by Earth's tilted axis. As Earth orbits the Sun,
+different hemispheres receive more direct sunlight at different times of year."
+Criterion: Factual Accuracy (weight: 1.0)
+Scale: 1-5
+```
+
+**Output**:
+```json
+{
+  "criterion": "Factual Accuracy",
+  "score": 5,
+  "evidence": [
+    "Correctly identifies axial tilt as primary cause",
+    "Correctly explains differential sunlight by hemisphere",
+    "No factual errors present"
+  ],
+  "justification": "Response accurately explains the cause of seasons with correct
+scientific reasoning. Both the axial tilt and its effect on sunlight distribution
+are correctly described.",
+  "improvement": "Could add the specific tilt angle (23.5 degrees) for completeness."
+}
+```
+
+### Example 2: Pairwise Comparison with Position Swap
+
+**Input**:
+```
+Prompt: "Explain machine learning to a beginner"
+Response A: [Technical explanation with jargon]
+Response B: [Simple analogy-based explanation]
+Criteria: ["clarity", "accessibility"]
+```
+
+**First Pass (A first)**:
+```json
+{ "winner": "B", "confidence": 0.8 }
+```
+
+**Second Pass (B first)**:
+```json
+{ "winner": "A", "confidence": 0.6 }
+```
+(Note: Winner is A because B was in first position)
+
+**Mapped Second Pass**:
+```json
+{ "winner": "B", "confidence": 0.6 }
+```
+
+**Final Result**:
+```json
+{
+  "winner": "B",
+  "confidence": 0.7,
+  "positionConsistency": {
+    "consistent": true,
+    "firstPassWinner": "B",
+    "secondPassWinner": "B"
+  }
+}
+```
+
+### Example 3: Rubric Generation
+
+**Input**:
+```
+criterionName: "Code Readability"
+criterionDescription: "How easy the code is to understand and maintain"
+domain: "software engineering"
+scale: "1-5"
+strictness: "balanced"
+```
+
+**Output** (abbreviated):
+```json
+{
+  "levels": [
+    {
+      "score": 1,
+      "label": "Poor",
+      "description": "Code is difficult to understand without significant effort",
+      "characteristics": [
+        "No meaningful variable or function names",
+        "No comments or documentation",
+        "Deeply nested or convoluted logic"
+      ]
+    },
+    {
+      "score": 3,
+      "label": "Adequate",
+      "description": "Code is understandable with some effort",
+      "characteristics": [
+        "Most variables have meaningful names",
+        "Basic comments present for complex sections",
+        "Logic is followable but could be cleaner"
+      ]
+    },
+    {
+      "score": 5,
+      "label": "Excellent",
+      "description": "Code is immediately clear and maintainable",
+      "characteristics": [
+        "All names are descriptive and consistent",
+        "Comprehensive documentation",
+        "Clean, modular structure"
+      ]
+    }
+  ],
+  "edgeCases": [
+    {
+      "situation": "Code is well-structured but uses domain-specific abbreviations",
+      "guidance": "Score based on readability for domain experts, not general audience"
+    }
+  ]
+}
+```
+
+## Guidelines
+
+1. **Always require justification before scores** - Chain-of-thought prompting improves reliability by 15-25%
+
+2. **Always swap positions in pairwise comparison** - Single-pass comparison is corrupted by position bias
+
+3. **Match scale granularity to rubric specificity** - Don't use 1-10 without detailed level descriptions
+
+4. **Separate objective and subjective criteria** - Use direct scoring for objective, pairwise for subjective
+
+5. **Include confidence scores** - Calibrate to position consistency and evidence strength
+
+6. **Define edge cases explicitly** - Ambiguous situations cause the most evaluation variance
+
+7. **Use domain-specific rubrics** - Generic rubrics produce generic (less useful) evaluations
+
+8. **Validate against human judgments** - Automated evaluation is only valuable if it correlates with human assessment
+
+9. **Monitor for systematic bias** - Track disagreement patterns by criterion, response type, model
+
+10. **Design for iteration** - Evaluation systems improve with feedback loops
+
+## Gotchas
+
+1. **Scoring without justification**: Scores lack grounding and are difficult to debug. Always require evidence-based justification before the score.
+
+2. **Single-pass pairwise comparison**: Position bias corrupts results when positions are not swapped. Always evaluate twice with swapped positions and check consistency.
+
+3. **Overloaded criteria**: Criteria that measure multiple things at once produce unreliable scores. Enforce one criterion = one measurable aspect.
+
+4. **Missing edge case guidance**: Evaluators handle ambiguous cases inconsistently without explicit instructions. Include edge cases in rubrics with clear resolution rules.
+
+5. **Ignoring confidence calibration**: High-confidence wrong judgments are worse than low-confidence ones. Calibrate confidence to position consistency and evidence strength.
+
+6. **Rubric drift**: Rubrics become miscalibrated as quality standards evolve or model capabilities improve. Schedule periodic rubric reviews and re-anchor score levels against fresh human-annotated examples.
+
+7. **Evaluation prompt sensitivity**: Minor wording changes in evaluation prompts (e.g., reordering instructions, changing phrasing) can cause 10-20% score swings. Version-control evaluation prompts and run regression tests before deploying prompt changes.
+
+8. **Uncontrolled length bias**: Longer responses systematically score higher even when conciseness is preferred. Add explicit length-neutrality instructions to evaluation prompts and validate with length-controlled test pairs.
+
+## Integration
+
+This skill integrates with:
+
+- **context-fundamentals** - Evaluation prompts require effective context structure
+- **tool-design** - Evaluation tools need proper schemas and error handling
+- **context-optimization** - Evaluation prompts can be optimized for token efficiency
+- **evaluation** (foundational) - This skill extends the foundational evaluation concepts
+
+## References
+
+Internal reference:
+- [LLM-as-Judge Implementation Patterns](./references/implementation-patterns.md) - Read when: building an evaluation pipeline from scratch or integrating LLM judges into CI/CD
+- [Bias Mitigation Techniques](./references/bias-mitigation.md) - Read when: evaluation results show inconsistent or suspicious scoring patterns
+- [Metric Selection Guide](./references/metrics-guide.md) - Read when: choosing statistical metrics to validate evaluation reliability
+- [Evaluation Pipeline Diagram](./references/evaluation-pipeline.md) - Read when: designing the architecture of a multi-stage evaluation system
+
+External research:
+- [Eugene Yan: Evaluating the Effectiveness of LLM-Evaluators](https://eugeneyan.com/writing/llm-evaluators/) - Read when: surveying the state of the art in LLM evaluation
+- [Judging LLM-as-a-Judge (Zheng et al., 2023)](https://arxiv.org/abs/2306.05685) - Read when: understanding position bias and MT-Bench methodology
+- [G-Eval: NLG Evaluation using GPT-4 (Liu et al., 2023)](https://arxiv.org/abs/2303.16634) - Read when: implementing chain-of-thought evaluation scoring
+- [Large Language Models are not Fair Evaluators (Wang et al., 2023)](https://arxiv.org/abs/2305.17926) - Read when: diagnosing systematic bias in evaluation outputs
+
+Related skills in this collection:
+- evaluation - Foundational evaluation concepts
+- context-fundamentals - Context structure for evaluation prompts
+- tool-design - Building evaluation tools
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-24
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0