drift: Skill for Claude Code

Drift Finding Message Authoring

Use this skill to write and review reason and next_action strings that are precise, actionable, and consistent with existing Drift finding output.

When To Use

• a new signal needs initial finding text
• an existing signal has unclear, vague, or non-actionable messages
• the ROADMAP task to sharpen finding explanations is being worked through
• a community report says a finding is confusing or hard to act on

Not For

• changing scoring, thresholds, or signal heuristics
• inventing new finding facts not supported by the signal logic
• rewriting output schemas or CLI formatting
• broad documentation work outside the signal file itself

Quality Criteria

Criterion	Pass condition
Cause specificity	Names the concrete code pattern, not a category
Jargon-free	Understandable without reading Drift docs
Actionability	next_action can be executed immediately
Length	Each field is at most 2 sentences
No hedging	Avoids phrases like "consider", "may", "possibly", or "might want to"

Core Rules

1. Preserve factual meaning. Improve clarity and actionability without changing what the signal actually detected.
2. Name the code pattern directly. Prefer the observed structure or smell over abstract category labels.
3. Make the next step concrete. next_action should tell the user exactly what to inspect, consolidate, remove, or move.
4. Keep output concise. Do not expand the message into explanation prose that belongs in docs or triage notes.
5. Review both fields together. A strong reason with a vague next_action, or the reverse, is incomplete.

Standard Workflow

1. Load The Existing Strings

Read the current reason and next_action from the target signal file under src/drift/signals/.

If one field is missing, treat that as a failure and author the missing field from the signal's actual detection logic.

2. Evaluate Against The Quality Criteria