Surprises

Detect and manage documentation surprises from Claude Code conversations.

2|Updated Jul 26, 2025

Search Tags:#workflow #documentation #claude #coordinator #surprises #surprise-investigator #surprise-reviewer

Ready to run

npx skills add https://github.com/fullykubed/nixos-config --skill surprises

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: Surprises
Source: https://github.com/fullykubed/nixos-config/tree/main/modules/common/claude/skills/Surprises
Command: npx skills add https://github.com/fullykubed/nixos-config --skill surprises

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, and includes scripts (resource) components.

What problem does it solve?

Automatically detect, track, and manage documentation discrepancies surfaced during Claude Code conversations, ensuring issues are surfaced, triaged, and resolved with repeatable processes.

Core Features & Use Cases

Detect and classify surprises across code, configuration, and documentation
Spawn surprise-investigator subagents to verify issues and produce formal surprise files
Support a two-workflow model (Review and Fix) with a centralized surprises store for traceability

Quick Start

Run the surprises workflow to detect, review, and fix documentation discrepancies from your conversations.

Frequently Asked Questions about Surprises

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I detect and track documentation discrepancies in Claude Code conversations?▼

Documentation discrepancies are detected by running the surprises workflow, which automatically identifies inconsistencies across code, config, and docs, then tracks them in a centralized store for resolution.

What is the best way to manage documentation surprises during code generation?▼

Managing documentation surprises involves a formal lifecycle using frontmatter metadata and a dedicated directory. Coordinator and investigator agents verify issues and produce structured surprise files for auditability.

Does detecting documentation surprises require installing any specific dependencies?▼

Yes, detecting and resolving documentation surprises requires the jq dependency to be installed in your environment to support the underlying scripts and workflow processing.

Can I classify documentation issues across both configuration and code files?▼

Yes, the workflow detects and classifies surprises across code, configuration, and documentation, ensuring that issues surfaced in Claude Code conversations are triaged consistently.

How to fix documentation inconsistencies after they have been reviewed?▼

Fixing documentation inconsistencies involves the two-workflow model, transitioning from the Review phase to the Fix phase to resolve tracked issues and update the structured surprise files.

When should I not use an automated surprise coordinator for documentation updates?▼

You should avoid using an automated surprise coordinator for simple, isolated text edits where a formal lifecycle with frontmatter metadata and dedicated directories adds unnecessary overhead.