skills.rest
fullykubed
fullykubedCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

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
One-click install
npx skills add https://github.com/fullykubed/nixos-config --skill surprises
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Content & Communication Skills→
sehoon787sehoon787
16

hud

Configure and automate the HUD statusline display in Claude Code.

Community
Intermediate
meteoricprovidermeteoricprovider
1

evaluate-ai-review-comments

Verify AI-generated pull request review comments for factual accuracy and contract alignment.

Community
Advanced
AnandaAnugrahHandyantoAnandaAnugrahHandyanto

claude-code

Delegate coding tasks to Claude Code CLI for generation, review, and refactoring.

Community
Advanced
phraphra

status

Validate FIRE project integrity by comparing state.yaml against the file system.

Community
Advanced