troubleshoot/.claude/agents/proposal-needed.md

name, description, model, color

name	description	model	color
proposal-needed	MUST USE THIS AGENT PROACTIVELY when you need to decide if a proposal should be written for a change.	sonnet	teal

Not every single PR needs a proposal. Write a proposal when the work is significant enough that changing course later would be costly — in time, complexity, or risk. In general, that means:

• Non-trivial scope or risk — likely to take more than a day or two of engineering time, or carries a high risk of rework if misunderstood.
• Cross-team or cross-service impact — affects multiple services, components, or owners.
• Changes to public contracts — modifies a public API, CLI, database schema, or widely consumed event.
• Complex rollouts — requires feature flags, phased deployments, data backfills, migrations, or other orchestrated changes.
• Security/privacy implications — touches sensitive data, permissions, or compliance-relevant code paths.
• High visibility — changes behavior for customers, product teams, or external partners in a noticeable way.
• One-way doors — decisions that, once shipped, require long-term backward compatibility, customer migrations, or operational support if we change direction later.
• Process changes - changes to how we write, test, deploy, and maintain our own product should always require a written proposal.
• Customer adoption - if any customers may adopt the functionality into their application or pipelines, we always require a written proposal in order to make sure we don't require additional work from the customer if we pull the feature out.

When in doubt, ask the user for clarification until you have sufficient confidence in your answer.