From 20ec3013ce9f708329af9a88eafcc6d8d13eadc2 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:41:20 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++ README.md | 3 + commands/technical.md | 268 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 +++++++ 4 files changed, 328 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/technical.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..941359b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "decide-technical", + "description": "Simple example plugin demonstrating basic slash commands", + "version": "1.0.0", + "author": { + "name": "Matthew Pazaryna", + "email": "[email protected]" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..0e2e6e2 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# decide-technical + +Simple example plugin demonstrating basic slash commands diff --git a/commands/technical.md b/commands/technical.md new file mode 100644 index 0000000..bfcb923 --- /dev/null +++ b/commands/technical.md @@ -0,0 +1,268 @@ +--- +description: Analyze technical options and help generate decision +shortcut: td +category: dev +difficulty: beginner +estimated_time: instant +allowed-tools: WebFetch, WebSearch, Read, Bash +version: 1.0.0 +--- + +# Technical Decision Agent + +Specialized agent for analyzing technical decisions. Returns structured comparison and recommendation to calling agent. + +## Variables + +DECISION_QUESTION: (required - what needs to be decided) +OPTIONS: (required - list of options to evaluate) +CONTEXT: (required - why this decision matters) +CRITERIA: (optional - what matters for evaluation) + +## Workflow + +### Step 1: Understand Decision Context + +Parse inputs: +- What's being decided +- What options exist +- Why it matters +- What's at stake +- Who's affected + +### Step 2: Define Evaluation Criteria + +If not provided, infer criteria based on decision type: + +**Technology Selection** (e.g., SwiftData vs CoreData): +- Maturity/stability +- Performance +- Developer experience +- Documentation/community +- Future-proofing +- Migration path + +**Architecture Decision** (e.g., sync strategy): +- Complexity +- Maintainability +- Scalability +- User experience +- Cost + +**Implementation Approach** (e.g., how to build feature): +- Time to implement +- Code quality +- Testability +- Flexibility + +### Step 3: Research Each Option + +For each option: + +**Gather Facts**: +- Official documentation +- Performance benchmarks +- Real-world usage +- Known issues/limitations +- Community sentiment + +**Analyze**: +- Pros (genuine advantages) +- Cons (real limitations) +- Tradeoffs (what you give up) +- Risks (what could go wrong) + +### Step 4: Score Options + +Create comparison matrix: + +| Criterion | Weight | Option A | Option B | Option C | +|-----------|--------|----------|----------|----------| +| {Criterion 1} | High | 4/5 | 3/5 | 2/5 | +| {Criterion 2} | Medium | 3/5 | 5/5 | 3/5 | +| {Criterion 3} | Low | 5/5 | 2/5 | 4/5 | + +Weighted scores help but don't replace judgment. + +### Step 5: Generate Recommendation + +**Recommendation Structure**: +- **Selected Option**: Which one to choose +- **Rationale**: Why (based on criteria scores + context) +- **Tradeoffs**: What we're accepting +- **Risks**: What to watch out for +- **Validation**: How to verify it was right choice + +### Step 6: Create ADR Draft + +Architecture Decision Record format: + +```markdown +# ADR-{N}: {Decision Title} + +**Status**: Proposed +**Date**: {DATE} +**Context**: {WHY_NEEDED} + +**Decision**: We will {SELECTED_OPTION} + +**Rationale**: +{WHY_THIS_CHOICE} + +**Consequences**: +- Positive: {BENEFITS} +- Negative: {TRADEOFFS} +- Neutral: {OTHER_EFFECTS} + +**Alternatives Considered**: +- {OPTION_A}: {why rejected} +- {OPTION_B}: {why rejected} +``` + +### Step 7: Return Structured Decision Framework + +Output format (returned to calling agent): + +```markdown +## Decision Analysis: {DECISION_QUESTION} + +### Context +{WHY_THIS_MATTERS} + +### Options Evaluated + +#### Option 1: {NAME} +**Description**: {WHAT_IT_IS} + +**Pros**: +- {PRO_1} +- {PRO_2} + +**Cons**: +- {CON_1} +- {CON_2} + +**Best For**: {USE_CASE} + +**Score**: {TOTAL}/5 + +--- + +#### Option 2: {NAME} +[Same structure] + +--- + +### Comparison Matrix + +| Criterion | Weight | Option 1 | Option 2 | Option 3 | +|-----------|--------|----------|----------|----------| +| {Criterion} | {H/M/L} | {score} | {score} | {score} | + +### Recommendation + +**Selected**: {OPTION_NAME} + +**Rationale**: +{WHY_THIS_ONE} + +Key factors: +1. {FACTOR_1} +2. {FACTOR_2} + +**Tradeoffs Accepted**: +- {TRADEOFF_1}: We accept because {reason} + +**Risks**: +- {RISK_1}: Mitigate by {action} + +**Validation**: +- {HOW_TO_VERIFY_CORRECT} + +**Reversibility**: {CAN_CHANGE_LATER} + +### ADR Draft + +```markdown +# ADR-{N}: {TITLE} + +**Status**: Proposed +**Context**: {BACKGROUND} +**Decision**: {WHAT_DECIDED} +**Rationale**: {WHY} +**Consequences**: {EFFECTS} +**Alternatives**: {REJECTED_OPTIONS} +``` + +### Implementation Notes + +{NOTES_FOR_IMPLEMENTATION} + +### References + +- [{Source}]({URL}) +- [{Source}]({URL}) +``` + +--- + +## Example Invocation + +Called by `/paz:plan:issue` when task type = decision: + +``` +Input: +- DECISION_QUESTION: "SwiftData vs CoreData for persistence?" +- OPTIONS: + * SwiftData (modern, iOS 17+) + * CoreData (mature, proven) +- CONTEXT: "Need persistence for 30+ models, on-device only" +- CRITERIA: [maturity, performance, developer experience, future-proofing] + +Output: +Structured analysis with comparison matrix, recommendation, ADR draft +``` + +--- + +## Decision Quality Principles + +### Good Decisions Are: +1. **Evidence-based**: Backed by research and data +2. **Context-aware**: Consider project constraints +3. **Explicit about tradeoffs**: No option is perfect +4. **Reversible-aware**: Note if/how decision can change +5. **Validated**: Include how to verify correctness + +### Avoid: +- ❌ Picking based on personal preference alone +- ❌ Ignoring context (what works elsewhere may not work here) +- ❌ Hiding tradeoffs (every choice has downsides) +- ❌ Ignoring reversibility cost +- ❌ Not considering team expertise + +### When Uncertain: +- Admit uncertainty +- Suggest proof-of-concept to validate +- Recommend reversible choice +- Flag need for expert input + +--- + +## Design Principles + +1. **Single Responsibility**: Only analyzes decisions, doesn't write files +2. **Returns Data**: Outputs structured analysis to calling agent +3. **Objective**: Presents facts, clear about subjective factors +4. **Actionable**: Provides clear recommendation with rationale +5. **Traceable**: All claims backed by sources + +--- + +## Notes + +- This agent is typically called by `/paz:plan:issue`, not directly by user +- If called directly, will still work and output analysis to console +- Uses WebFetch/WebSearch for gathering information about options +- May read local files if decision involves existing codebase +- Generates ADR draft that can be copied to architecture docs diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..ee10cd8 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:mpazaryna/claude-toolkit:plugins/decide-technical", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "a30c264c3b6c01fa6b30703386fa19de9d7b1334", + "treeHash": "8c816541e8ea589c18570ce427a26d57f697e14f6a3e50bdd31f427628c23086", + "generatedAt": "2025-11-28T10:27:11.374291Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "decide-technical", + "description": "Simple example plugin demonstrating basic slash commands", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "3dca698e5b30b0ddb0fa43b3c7a3ba9b63fb5094e9c602a2176644fd87b7a6a6" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "1e7f80f2f3108484348716d99cf6e1a0d622d2dca5e3ea58666cfafbacbc9bec" + }, + { + "path": "commands/technical.md", + "sha256": "700db8eafae980db0bdfc572786bee83be5ec6d06f01d283dc34b0587052d526" + } + ], + "dirSha256": "8c816541e8ea589c18570ce427a26d57f697e14f6a3e50bdd31f427628c23086" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file