name: one-three-one-rule description: > Structured decision-making framework for technical proposals and trade-off analysis. When the user faces a choice between multiple approaches (architecture decisions, tool selection, refactoring strategies, migration paths), this skill produces a 1-3-1 format: one clear problem statement, three distinct options with pros/cons, and one concrete recommendation with definition of done and implementation plan. Use when the user asks for a "1-3-1", says "give me options", or needs help choosing between competing approaches. version: 1.1.0 author: Willard Moore license: MIT category: communication metadata: hermes: tags: [communication, decision-making, proposals, trade-offs] evaluations: path: evaluations/golden.jsonl description: Golden eval cases validating 1-3-1 format compliance and decision-making quality.
Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
Keep it tight. If you need "and", you're describing two problems.
Options (exactly three)
Options should represent genuinely different strategies, not minor variations of the same approach.
Recommendation (one option)
Be direct — this is your professional judgment, not a hedge.
Definition of Done
If the user picks a different option, revise this section to match.
Implementation Plan
After presenting your recommendation, do NOT hedge or ask for permission. Do not end with "What do you think?", "你觉得怎么样", "Shall I proceed?", or any other move that defers the decision back to the user. The recommendation IS your professional judgment — deliver it as a conclusion, not a proposal.
If you have multiple actionable items ranked by priority, state them in priority order with clear reasoning. The user will tell you which to execute when ready.
User: "Give me a 1-3-1 for adding retry logic to our API client."
Agent:
Problem: API calls to external services fail intermittently under load and need graceful retry handling.
Options:
Option A: Exponential backoff with jitter in a shared utility. Pros: Simple, well-understood pattern; single implementation shared across all callers. Cons: No circuit-breaking; callers still block during retries.
Option B: Retry library (tenacity) as a decorator on each endpoint call. Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits. Cons: Adds a dependency; decorator pattern can obscure control flow.
Option C: Queue-based async retry with dead letter handling. Pros: Non-blocking; failed calls are tracked and replayable; scales well. Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
Recommendation: Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
Definition of Done:
- api_retry() utility handles transient HTTP errors (429, 502, 503, 504).
- Retries up to 3 times with exponential backoff and jitter.
- All external API calls route through the retry utility.
- Logs each retry attempt with endpoint and attempt number.
- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
Implementation Plan:
1. Create utils/api_retry.py with configurable max retries, base delay, and retryable status codes.
2. Add jitter using random.uniform(0, base_delay) to prevent thundering herd.
3. Wrap existing API calls in api_client.py with the retry utility.
4. Add unit tests mocking HTTP responses for each retry scenario.
5. Verify under load with a simple stress test against a flaky endpoint mock.