diff --git a/optional-skills/communication/DESCRIPTION.md b/optional-skills/communication/DESCRIPTION.md new file mode 100644 index 000000000..2f44b53b8 --- /dev/null +++ b/optional-skills/communication/DESCRIPTION.md @@ -0,0 +1 @@ +Communication and decision-making frameworks — structured response formats for proposals, trade-off analysis, and stakeholder-ready recommendations. diff --git a/optional-skills/communication/one-three-one-rule/SKILL.md b/optional-skills/communication/one-three-one-rule/SKILL.md new file mode 100644 index 000000000..ca0ccd449 --- /dev/null +++ b/optional-skills/communication/one-three-one-rule/SKILL.md @@ -0,0 +1,103 @@ +--- +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.0.0 +author: Willard Moore +license: MIT +category: communication +metadata: + hermes: + tags: [communication, decision-making, proposals, trade-offs] +--- + +# 1-3-1 Communication Rule + +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. + +## When to Use + +- The user explicitly asks for a "1-3-1" response. +- The user says "give me options" or "what are my choices" for a technical decision. +- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy). +- The user needs a proposal they can forward to a team or stakeholder. + +Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach. + +## Procedure + +1. **Problem** (one sentence) + - State the core decision or desired outcome in a single concise sentence. + - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies. + - Keep it tight. If you need "and", you're describing two problems. + +2. **Options** (exactly three) + - Present three distinct, viable approaches labeled A, B, C. + - Each option gets a brief description, pros, and cons. + - Options should represent genuinely different strategies, not minor variations of the same approach. + +3. **Recommendation** (one option) + - State which option you recommend and why, based on the user's context and priorities. + - Be direct — this is your professional judgment, not a hedge. + +4. **Definition of Done** + - List the specific success criteria for the recommended option. + - These are concrete, verifiable outcomes — not vague aspirations. + - If the user picks a different option, revise this section to match. + +5. **Implementation Plan** + - Concrete steps to execute the recommended option. + - Include specific commands, tools, or actions where applicable. + - If the user picks a different option, revise this section to match. + +## Verification + +- Response has exactly one Problem sentence. +- Response has exactly three Options (A, B, C) with pros and cons for each. +- Response has a single Recommendation that picks one option with reasoning. +- Definition of Done and Implementation Plan align with the recommended option. +- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly. + +## Example + +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.