diff --git a/AGENTS.md b/AGENTS.md index a342e62..d1939a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -136,6 +136,7 @@ When the user mentions these keywords, load the corresponding skill: | "mermaid-diagrams", "mermaid diagrams" | [mermaid-diagrams](mermaid-diagrams/SKILL.md) | | "adr-authoring", "adr authoring" | [adr-authoring](adr-authoring/SKILL.md) | | "c4-diagramming", "c4 diagramming" | [c4-diagramming](c4-diagramming/SKILL.md) | +| "technology-radar", "technology radar" | [technology-radar](technology-radar/SKILL.md) | ## Use-When Sections Every skill description must identify when to load it. Skills with meaningful overlap should also include a `## When not to use` section naming the nearest alternative or prerequisite. Keep these sections trigger-oriented and concise; implementation details belong in references. diff --git a/README.md b/README.md index 8f5d552..1bfa120 100644 --- a/README.md +++ b/README.md @@ -227,6 +227,10 @@ Spec-Driven Development (SDD) methodology for AI software factories — where st Make documentation useful at the moment someone needs to install, operate, extend, or troubleshoot a system. +### [technology-radar](technology-radar/SKILL.md) + +Turn scattered technology preferences into explicit, reviewable decisions with owners, evidence, and a clear adoption posture. + ### [three](three/SKILL.md) Build browser-based Three.js and WebGL scenes, animations, and interactive 3D visualizations. diff --git a/technology-radar/README.md b/technology-radar/README.md new file mode 100644 index 0000000..f397654 --- /dev/null +++ b/technology-radar/README.md @@ -0,0 +1,36 @@ +# Technology Radar + +Turn scattered technology preferences into explicit, reviewable decisions with owners, evidence, and a clear adoption posture. + +## Why Install This Skill + +Turn scattered technology preferences into explicit, reviewable decisions with owners, evidence, and a clear adoption posture. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer. + +Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator. + +## What You Get + +| Path | What it provides | +|---|---| +| `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. | +| `references/` | Reference material: `architecture-governance.md`, `build-vs-buy.md`, `engineering-metrics.md`, `technology-radar.md` | + +## Quick Start + +Read `references/technology-radar.md`, then use the decision criteria in `SKILL.md` to create or update a radar entry. + +Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below. + +## Triggers + +- Build and maintain technology radars for adoption, trial, assessment, and hold decisions. Use when governing technology choices, build-versus-buy decisions, or engineering portfolio risk. +- Requests involving the method, deliverables, or review process described in `SKILL.md`. +- Work where a reusable template or reference from this skill would reduce avoidable mistakes. + +## Requirements + +No runtime dependency. + +## Source and maintenance + +This skill was extracted from [`magnus919/hermes-profiles`](https://github.com/magnus919/hermes-profiles) at commit [`867a555`](https://github.com/magnus919/hermes-profiles/commit/867a555). The portable methodology was retained; Hermes-specific profile, orchestration, and memory assumptions were removed. diff --git a/technology-radar/SKILL.md b/technology-radar/SKILL.md new file mode 100644 index 0000000..46a5fed --- /dev/null +++ b/technology-radar/SKILL.md @@ -0,0 +1,61 @@ +--- +name: technology-radar +description: Build and maintain technology radars for adoption, trial, assessment, and hold decisions. Use when governing technology choices, build-versus-buy decisions, or engineering portfolio risk. +license: MIT +compatibility: No runtime dependency. +metadata: + source_repo: https://github.com/magnus919/hermes-profiles + source_commit: 867a555 +--- + + +# Technology Radar + +CTO methodology for making technology decisions, governing architecture, measuring engineering effectiveness, managing technical debt, and operating an innovation pipeline. These frameworks help a CTO balance short-term delivery velocity with long-term platform health. + +## Domain Model + +| Domain | Covers | Artifact | +|--------|--------|----------| +| **Technology Radar** | Adopt/Trial/Assess/Hold quadrants, tool selection criteria, deprecation policy | Technology radar document | +| **Build vs Buy** | TCO analysis, decision matrices, vendor evaluation, integration cost | Build-vs-buy recommendation | +| **Architecture Governance** | Standards, review boards, RFC process, design reviews | ADRs, RFC documents, governance charter | +| **Engineering Metrics** | DORA (deploy frequency, lead time, MTTR, change failure rate), SPACE, DevEx | Engineering dashboard, health report | +| **Technical Debt** | Interest calculation, remediation prioritization, principal estimation | Technical debt register | +| **Innovation Pipeline** | Horizon scanning, POC criteria, production readiness gates | Innovation funnel, POC report | + +## When to Load + +Load this skill when the task involves: + +- Evaluating a new technology or tool for adoption +- Making a build-vs-buy decision with TCO analysis +- Designing or auditing architecture governance processes +- Setting up engineering metrics dashboards (DORA, SPACE) +- Quantifying and prioritizing technical debt remediation +- Running an innovation pipeline with POC-to-production gates +- Deprecating or retiring legacy technology +- Conducting an architecture review board session + + +## Reference Files + +| Reference | Load When | File | +|-----------|-----------|------| +| Technology Radar | You need to evaluate and categorize a technology or tool for adoption, trial, assessment, or hold | `references/technology-radar.md` | +| Build vs Buy | You're comparing build vs buy options with TCO analysis and decision criteria | `references/build-vs-buy.md` | +| Architecture Governance | You're designing RFC processes, review boards, or architecture standards | `references/architecture-governance.md` | +| Engineering Metrics | You need to measure engineering effectiveness with DORA, SPACE, or DevEx frameworks | `references/engineering-metrics.md` | + +## Design Principles + +1. **Technology is a means, not an end.** Every technology decision must trace back to a business outcome. "Because it's new" is not a reason to adopt. "Because it solves X faster/safer/cheaper" is. +2. **Radar is a living document.** A technology radar updated once a year is a museum. Update it quarterly, or every time a significant adoption/hold/promote/promote-to-trial decision is made. +3. **Build vs buy is never just cost.** Total Cost of Ownership includes maintenance, hiring, training, integration, migration, and opportunity cost. A cheaper build today may be vastly more expensive over 3 years. +4. **Engineering metrics measure the system, not the people.** DORA metrics measure the delivery capability of the org. SPACE measures developer satisfaction. Neither is a performance review tool for individuals. +5. **Technical debt has a principal and an interest payment.** The principal is the cost to fix it properly. The interest is the recurring drag on velocity. Prioritize debt where interest/principal ratio is highest. +6. **Production readiness gates exist to prevent crisis.** Every gate that is skipped in the name of speed will be paid for in incident response time later. + +## Portability + +This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format. diff --git a/technology-radar/references/architecture-governance.md b/technology-radar/references/architecture-governance.md new file mode 100644 index 0000000..b4f951f --- /dev/null +++ b/technology-radar/references/architecture-governance.md @@ -0,0 +1,126 @@ +# Architecture Governance + +Frameworks for maintaining architectural coherence, making design decisions transparent, and ensuring the technology organization operates with aligned standards. + +## Architecture Standards + +Standards exist to reduce cognitive load and ensure consistency. They should be few, well-justified, and enforced through automation, not manual review. + +### What Should Be Standardized + +| Tier | Category | Example Standards | Enforcement | +|------|----------|-------------------|-------------| +| **Tier 1: Mandatory** | Security, compliance, legal | Data encryption, auth patterns, audit logging | Automated (CI pipeline blocks) | +| **Tier 2: Expected** | Architecture, deployment | Service boundaries, API design, container patterns | Reviewed (RFC approval required for exceptions) | +| **Tier 3: Recommended** | Tooling, patterns | CI/CD tool, monitoring approach, logging format | Documented (teams may deviate with justification) | + +### Writing Architecture Standards + +Each standard should contain: + +1. **Title.** What the standard governs. +2. **Rationale.** Why this standard exists. If you can't articulate the benefit, question the standard. +3. **Scope.** What systems/teams this applies to (and what it explicitly does not). +4. **The standard.** The specific requirement. Measurable, testable, unambiguous. +5. **Exception process.** How to request an exception and who can grant it. +6. **Review date.** When this standard will be re-evaluated. + +### Standards Anti-Patterns + +- **Too many standards.** If everything is a standard, nothing is. Limit Tier 1 and Tier 2 to 15-20 items total. +- **Standards without automation.** If compliance requires a human reviewer, the standard will be applied inconsistently. Automate everything possible. +- **Stale standards.** A standard that hasn't been reviewed in 2+ years is likely causing harm. Sunset or update. +- **The "we've always done it this way" standard.** Justify every standard independently. Past practice is not a rationale. + +--- + +## Architecture Review Board (ARB) + +An ARB provides governance for significant architecture decisions. It is not a bottleneck — it is a quality gate and knowledge-sharing mechanism. + +### When to Involve the ARB + +| Level | Decision Type | Review Process | +|-------|--------------|----------------| +| **L1: Team-level** | Service internal design, API endpoints, database schema | No ARB needed. Team decides. | +| **L2: Cross-team** | New service, shared library, API contract change | ARB notified, lightweight review (1-2 reviewers) | +| **L3: Organization-wide** | New technology, platform change, infrastructure redesign | Full ARB review (RFC + meeting) | +| **L4: Strategic** | Architecture paradigm shift (monolith → microservices, cloud migration) | Executive + ARB joint review | + +### ARB Composition + +| Role | Responsibility | Count | +|------|---------------|-------| +| **Chair** | Manages agenda, drives decisions, maintains standards | 1 | +| **Principal Architects** | Technical authority, deep domain expertise | 2-4 | +| **Rotating Members** | Cross-functional representation, bring team context | 2-3 (rotating quarterly) | +| **Decision Author** | Presents the proposal, answers questions | 1 per proposal | + +### Effective ARB Practices + +- **Time-boxed meetings.** One hour max. Decisions should be prepared before the meeting, not debated from scratch. +- **Written proposals required.** No "let's whiteboard it" in the ARB. Proposals must be submitted as RFCs at least 48 hours in advance. +- **Decisions, not discussions.** The ARB's job is to make a decision: approve, approve with conditions, or reject with feedback. Not to explore options. +- **Rotating membership.** Fixed members create an insular culture. Rotate members quarterly to distribute knowledge and prevent groupthink. +- **Appeals process.** Any rejected RFC can be appealed to the CTO or VP Engineering. This prevents the ARB from becoming a bottleneck. + +--- + +## RFC Process + +Request for Comments (RFC) is a lightweight process for making significant technical decisions transparent and documented. + +### The RFC Lifecycle + +1. **Draft.** Author writes the RFC using the template below. Collaborate with stakeholders. +2. **Review.** RFC is open for comments for a minimum period (typically 3-5 business days). +3. **Decision.** The decision-maker (tech lead, ARB chair, CTO) approves, conditionally approves, or rejects. +4. **Implementation.** Approved RFCs are implemented. The RFC becomes the source of truth for the decision. +5. **Retrospective.** After implementation, close the RFC with a summary of what changed from the original design. + +### RFC Template + +```markdown +# RFC: [Title] + +## Status +[Draft | Review | Approved | Rejected | Implemented] + +## Summary +[2-3 sentence overview of the proposal] + +## Motivation +[Why this change is needed. What problem does it solve? What happens if we don't do it?] + +## Design +[The proposed solution. Architecture diagrams, API contracts, data models.] + +## Alternatives Considered +[Other approaches and why they were not chosen. Include the runner-up.] + +## Trade-offs +[What are we giving up? Performance vs maintainability? Speed vs correctness?] + +## Migration Plan +[How do we get from current state to proposed state? Phased approach, timeline, rollback plan.] + +## Open Questions +[What we don't know yet. Decisions that are deferred.] + +## Appendix +[Any additional context, benchmarks, or references.] +``` + +### RFC Principles + +- **Write-first, talk-second.** Discussions happen on the document. Meetings are for resolving deadlocked issues, not for initial review. +- **Disagree and commit.** Once a decision is made, the team commits to implementing it. Continued debate after a decision undermines the process. +- **Explicit deferral.** "Let's discuss this in the meeting" is fine. "Let's discuss this later" without a specific time is delay. Set a deadline for every deferred question. +- **Retrospectives on rejected RFCs.** If an RFC is rejected, document why. The analysis may be valuable if conditions change later. + +### Common RFC Failures + +- **The design-by-committee RFC.** Too many authors, too many opinions, no clear vision. RFCs should have one primary author and 1-2 reviewers. +- **RFC as a rubber stamp.** If the decision is already made and the RFC is just documentation, that's fine — but be explicit. "Decision made: we're moving to X. This RFC documents the design and migration plan." +- **Too much detail, too late.** An RFC that describes a fully detailed implementation is harder to change than one that starts with the high-level approach. Get alignment on the approach before diving into implementation details. +- **Death by process.** If every minor change requires an RFC, engineers will stop writing RFCs. Define the threshold clearly. diff --git a/technology-radar/references/build-vs-buy.md b/technology-radar/references/build-vs-buy.md new file mode 100644 index 0000000..3a09c26 --- /dev/null +++ b/technology-radar/references/build-vs-buy.md @@ -0,0 +1,128 @@ +# Build vs Buy Decision Framework + +A systematic approach to evaluating whether to build a capability internally or buy/license it from a vendor. The decision is never just about cost — it's about strategic control, opportunity cost, and long-term flexibility. + +## Decision Tree + +Use this as the first filter before doing any detailed analysis: + +``` +Is this capability core to our competitive advantage? +├── YES → Is it available to buy with acceptable terms? +│ ├── YES → Buy, but plan to insource over time +│ └── NO → Build (strategic investment) +└── NO → Is it a commodity? + ├── YES → Buy (cheaper, faster, maintained) + └── NO → Is the vendor market mature? + ├── YES → Buy (market has validated solutions) + └── NO → Build or partner (market is too immature) +``` + +## TCO Analysis + +Total Cost of Ownership over a 3-year period. The first-year cost is often misleading — the true cost comparison requires a multi-year view. + +### Build Costs (3-Year TCO) + +| Cost Category | Year 1 | Year 2 | Year 3 | Total | +|---------------|--------|--------|--------|-------| +| Engineering (design + build) | $XXX | $XX | $XX | $XXX | +| Infrastructure (hosting, CDN, DB) | $XX | $XX | $XX | $XXX | +| Ongoing maintenance (20% of build/yr) | $0 | $XX | $XX | $XXX | +| Support & on-call rotation | $XX | $XX | $XX | $XXX | +| Documentation & training | $X | $X | $X | $XXX | +| Opportunity cost (what else could this team build?) | $XXX | $XXX | $XXX | $XXX | + +### Buy Costs (3-Year TCO) + +| Cost Category | Year 1 | Year 2 | Year 3 | Total | +|---------------|--------|--------|--------|-------| +| License/subscription fees | $XX | $XX | $XX | $XXX | +| Implementation & migration | $XX | $0 | $0 | $XX | +| Custom integration | $XX | $X | $X | $XXX | +| Training | $X | $X | $X | $XXX | +| Vendor management overhead | $X | $X | $X | $XXX | +| Renewal escalation (3-10% annual) | $0 | $X | $XX | $XXX | +| Exit cost (if vendor changes terms) | $0 | $0 | $0 | $XXX (contingent) | + +### Hidden Costs (Often Missed) + +**Build hidden costs:** +- Testing and QA infrastructure +- Security hardening and compliance certification +- Internal user support and troubleshooting +- Documentation maintenance +- Technical debt from rushed delivery +- Knowledge loss if a key engineer leaves + +**Buy hidden costs:** +- Data egress/ingress fees +- Integration maintenance across vendor API changes +- Vendor lock-in (data portability, migration cost) +- Feature gaps that require workarounds +- SLA enforcement and vendor management +- Multiple vendor coordination in the same workflow + +--- + +## Decision Matrix + +After TCO analysis, score both options against weighted criteria. + +### Standard Criteria + +| Criterion | Typical Weight | Build Score (1-5) | Buy Score (1-5) | +|-----------|---------------|-------------------|-----------------| +| Strategic alignment | 25% | | | +| Total cost (3-year) | 20% | | | +| Time to value | 15% | | | +| Customizability | 15% | | | +| Maintenance burden | 10% | | | +| Vendor risk/lock-in | 10% | | | +| Team satisfaction | 5% | | | + +### Scoring Template + +``` +Criterion: Strategic alignment +- 5: Directly creates competitive advantage, core to our moat +- 3: Supports the business but not differentiating +- 1: Commodity capability + +Criterion: Time to value +- 5: Working in <1 month +- 3: Working in 1-3 months +- 1: Working in >6 months + +Criterion: Maintenance burden +- 5: Near-zero maintenance (vendor handles everything) +- 3: Regular maintenance, dedicated team not required +- 1: Requires dedicated team for ongoing maintenance +``` + +--- + +## When Build is Right + +1. **Core differentiator.** The capability is central to your competitive advantage. Owning it gives you control over your product's future. +2. **No adequate vendor.** The market doesn't offer what you need, or vendors are too immature/unstable. +3. **Existing capability.** You already built something similar. The marginal cost of extending it is lower than buying. +4. **Data advantage.** Your proprietary data makes the build significantly better than any off-the-shelf solution. +5. **Cost structure.** At scale, the build becomes dramatically cheaper than buying (common in infrastructure). + +## When Buy is Right + +1. **Commodity capability.** Payroll, email, analytics, maps, auth. Don't build what everyone already has. +2. **Speed to market.** The vendor can have you running in days. Building would take months. +3. **Non-core.** The capability is necessary but not differentiating. Buy preserves engineering capacity for what matters. +4. **Mature vendor market.** Multiple vendors compete on the feature you need. Price and quality are market-validated. +5. **Difficult to build well.** Encryption, compliance, payment processing, fraud detection. These domains have deep complexity and regulatory requirements. + +## Build vs Buy Anti-Patterns + +- **The "it's simple" fallacy.** "How hard can it be to build a chat system?" Very hard, if you need reliability, search, file sharing, compliance, and mobile sync. +- **The "we'll save money" trap.** First-year cost favors build. Three-year TCO with maintenance, support, and opportunity cost often favors buy. +- **Build because we're engineers.** Engineers want to build things. That doesn't mean they should build everything. The company's strategic priorities, not engineering preferences, should drive the decision. +- **Buy because we're in a hurry.** Urgency isn't a decision framework. A rushed buy that doesn't fit the architecture costs more than a delayed build. +- **The "not invented here" syndrome.** Organizational pride in building internally. Recognize it and evaluate honestly. +- **The "invented here" syndrome.** The opposite — assuming external vendors are always better. Apply the same scrutiny either way. diff --git a/technology-radar/references/engineering-metrics.md b/technology-radar/references/engineering-metrics.md new file mode 100644 index 0000000..f2a3232 --- /dev/null +++ b/technology-radar/references/engineering-metrics.md @@ -0,0 +1,115 @@ +# Engineering Metrics + +Frameworks for measuring engineering effectiveness, developer productivity, and delivery health. The goal is insight, not judgment — metrics should inform improvement, not evaluate individuals. + +## DORA Metrics + +DORA (DevOps Research and Assessment) defines four key metrics that predict organizational performance. They are the most widely adopted benchmark for software delivery capability. + +### The Four Metrics + +| Metric | Definition | Elite | High | Medium | Low | +|--------|-----------|-------|------|--------|-----| +| **Deployment Frequency** | How often code is deployed to production | On demand (multiple/day) | Between once/day and once/week | Between once/week and once/month | Between once/month and once/6 months | +| **Lead Time for Changes** | Time from commit to production | < 1 hour | < 1 day | < 1 week | > 6 months | +| **Mean Time to Recover (MTTR)** | Time to restore service after incident | < 1 hour | < 1 day | < 1 day | > 1 week | +| **Change Failure Rate** | % of deployments causing a failure | 0-5% | 5-10% | 10-15% | 15%+ | + +### Benchmarking + +Use these benchmarks to understand where your organization falls, but don't chase elite performance if your context doesn't require it. + +| Industry | Typical Performance | +|----------|-------------------| +| SaaS (consumer) | High to Elite | +| SaaS (enterprise) | Medium to High | +| Fintech/Healthcare | Low to Medium (regulatory constraints) | +| Hardware/Firmware | Low to Medium | +| Internal tools | Varies widely | + +### Improving DORA Metrics + +| Metric | Lever | Intervention | +|--------|-------|-------------| +| Deployment frequency | Trunk-based development, CI/CD automation | Adopt feature flags, automate testing, reduce batch size | +| Lead time | Review speed, CI pipeline, deploy automation | Small PRs, auto-merge on passing CI, deploy previews | +| MTTR | Observability, incident response, rollback capability | Monitoring investment, incident playbooks, canary deployments | +| Change failure rate | Testing, code review, gradual rollout | Automated testing pyramid, load testing, feature flags | + +### DORA Pitfalls + +- **Measuring without context.** A low change failure rate might mean "good engineering" or "never deploying." Always interpret metrics together. +- **Comparing teams directly.** Teams doing different work will have different DORA profiles. Compare a team to its own trend, not to other teams. +- **Chasing elite on all four.** Some contexts (regulatory, safety-critical) cannot achieve elite change failure rate or lead time. Optimize for your constraints. + +--- + +## SPACE Framework + +DORA measures delivery. SPACE measures the human side of productivity — developer satisfaction and the quality of their work experience. + +### The Dimensions + +| Dimension | What It Measures | Sample Metrics | +|-----------|-----------------|----------------| +| **S**atisfaction & Well-being | How developers feel about their work, tools, and environment | eNPS, burnout survey, tool satisfaction score | +| **P**erformance | Outcomes and value delivered | Deploy frequency, feature adoption, MTTR | +| **A**ctivity | Quantity of output (use with caution) | PRs created, code reviews completed, commits | +| **C**ommunication & Collaboration | How effectively developers work together | Review cycle time, cross-team PRs, docs contributions | +| **E**fficiency & Flow | How easily developers can stay in flow state | Time in IDE, context switches, wait time for reviews | + +### Using SPACE + +- **Don't track all five equally.** Pick 2-3 dimensions that matter for your current challenges. If burnout is the issue, focus on Satisfaction. If bottlenecks are the issue, focus on Flow. +- **Pair SPACE with DORA.** DORA measures the system. SPACE measures the people. Both are needed for a complete picture. +- **Survey quarterly, not weekly.** Satisfaction and well-being don't change fast enough for frequent measurement. Quarterly surveys + monthly pulse checks. +- **Avoid activity myopia.** "PRs per developer" alone drives bad behavior (tiny PRs). Always pair activity metrics with outcome metrics. + +### Common SPACE Anti-Patterns + +- **Treating satisfaction as a metric.** It's a dimension. The metric within it should be specific (e.g., "I have adequate time for focused work" scored 1-5). +- **Survey fatigue.** If you survey developers about satisfaction too often, they stop giving honest answers. +- **Ignoring the results.** Asking developers about their experience and then doing nothing is worse than not asking at all. Close the feedback loop publicly. + +--- + +## DevEx (Developer Experience) + +Developer Experience focuses on the friction developers encounter in their daily work. Reducing friction is a force multiplier — minutes saved per developer translate to significant organizational throughput. + +### The DevEx Framework + +| Layer | What It Covers | Friction Signals | +|-------|---------------|-----------------| +| **Local Development** | IDE, dev environment, local testing | Long build times, complex setup, "it works on my machine" | +| **Inner Loop** | Code, build, test, debug cycle | Slow feedback, flaky tests, context switching | +| **Outer Loop** | CI/CD, review, deploy, monitor | Long CI, slow reviews, complex deployment | +| **Cognitive Load** | How much a developer needs to know | Complexity of architecture, number of tools, documentation quality | + +### Measuring DevEx + +| Method | What It Captures | Frequency | +|--------|-----------------|-----------| +| **Developer survey (Dx or SPACE)** | Subjective experience, satisfaction | Quarterly | +| **Time-to-first-commit** | Onboarding friction | Tracked per new hire | +| **IDE time in flow** | Focused work time | Weekly (via tool telemetry) | +| **Build/CI wait times** | Infrastructure bottlenecks | Weekly | +| **Context switch count** | Fragmentation of work | Monthly via calendar analysis | + +### DevEx Improvement Levers + +| Lever | Impact | Effort | +|-------|--------|--------| +| Standardized development environment (DevContainer, Nix) | High | Medium | +| Local development with production-like data | High | Medium-High | +| CI/CD pipeline optimization | Medium-High | Medium | +| Documentation-as-code for architecture decisions | Medium | Low | +| Automated dev environment setup (single command) | High | Medium | +| Flaky test remediation | High | Medium | + +### DevEx Pitfalls + +- **Building internal tools that don't solve real friction.** Survey developers about their top 3 pains before building anything. +- **Measuring the wrong thing.** Time in IDE could mean "in flow" or "stuck and trying to figure things out." Combine tool data with qualitative feedback. +- **One-size-fits-all solutions.** Different teams have different friction points. Let teams opt into platform improvements rather than mandating them. +- **Ignoring cognitive load.** The most expensive friction is mental — having to keep too many details in your head to be productive. Invest in abstractions and documentation. diff --git a/technology-radar/references/source-index.md b/technology-radar/references/source-index.md new file mode 100644 index 0000000..c1378a1 --- /dev/null +++ b/technology-radar/references/source-index.md @@ -0,0 +1,6 @@ +# Source index + +- **Source repository:** https://github.com/magnus919/hermes-profiles +- **Inspected commit:** `867a555` +- **Imported source directory:** `technology-radar` +- **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions. diff --git a/technology-radar/references/technology-radar.md b/technology-radar/references/technology-radar.md new file mode 100644 index 0000000..d888595 --- /dev/null +++ b/technology-radar/references/technology-radar.md @@ -0,0 +1,106 @@ +# Technology Radar + +The technology radar is a structured approach to tracking, evaluating, and deciding on technologies. It categorizes technologies into four quadrants and two rings. + +## The Radar Framework + +### Quadrants (Technology Categories) + +| Quadrant | What It Covers | Example | +|----------|---------------|---------| +| **Languages & Frameworks** | Programming languages, web frameworks, application frameworks | Python, React, Django, Go | +| **Platforms & Infrastructure** | Cloud providers, container orchestration, databases, message queues | Kubernetes, AWS, Postgres, Kafka | +| **Tools & Techniques** | CI/CD, monitoring, testing, security scanning, project management | GitHub Actions, Prometheus, Terraform | +| **Patterns & Practices** | Architectural patterns, development methodologies, operational practices | Microservices, event sourcing, GitOps | + +### Rings (Maturity Levels) + +| Ring | Meaning | Policy | +|------|---------|--------| +| **Adopt** | Proven in production, recommended for all relevant new projects | Actively promoted, documented standards exist | +| **Trial** | Worth pursuing, low-risk to experiment | Sandboxed POC allowed, must revisit decision within 6 months | +| **Assess** | Worth investigating, but not ready for commitment | Research and small experiments only, no production use | +| **Hold** | Not recommended for new projects, plan migration away | No new usage, existing usage must have migration plan | + +### Transition Rules + +| Transition | When | Process | +|------------|------|---------| +| Assess → Trial | Team assessed, sees potential, has a POC plan | Brief written recommendation, tech lead approval | +| Trial → Adopt | Successful in 2+ projects with documented results | Full review, standardization of patterns, documentation | +| Adopt → Hold | Newer better alternative, maintenance burden, strategic shift | Migration plan for existing systems, deprecation notice | +| Hold → (Retire) | No remaining users, migration complete | Archive docs, remove from supported list | +| Trial → Hold | Experiment failed the thesis | Document learnings, archive. Not a failure — it's data. | + +### Radar Review Cadence + +- **Full radar refresh:** Quarterly (review all quadrants and rings) +- **New technology intake:** Continuous (proposed via RFC or lightweight form) +- **Emergency promotion:** As needed (critical security update, strategic shift) +- **Hold review:** Annual (verify hold decisions are still valid) + +--- + +## Tool Selection Criteria + +When evaluating whether to Adopt, Trial, or Hold a technology, use this criteria framework. + +### Evaluation Dimensions + +| Dimension | Weight | Scoring (1-5) | Notes | +|-----------|--------|---------------|-------| +| **Fit for purpose** | 30% | Does it solve the actual problem? | Beware over-engineering. "Does it work?" is the first question. | +| **Community & ecosystem** | 20% | Active development, documentation, community support | GitHub stars, contributor count, release cadence, Stack Overflow activity | +| **Operational maturity** | 20% | Production readiness, monitoring, upgrade stability | Does the community have a track record of stable releases? | +| **Talent availability** | 15% | Can we hire/develop people who know this? | Market availability, learning curve, internal expertise | +| **Integration complexity** | 15% | How hard is it to integrate with our existing stack? | Migration cost, interoperability, dependency conflicts | + +### Scoring Guide + +| Score | Meaning | +|-------|---------| +| 5 | Excellent — best in class for our context | +| 4 | Good — strong fit with minor concerns | +| 3 | Adequate — works but not differentiated | +| 2 | Poor — significant concerns | +| 1 | Unacceptable — does not meet requirements | + +### Red Flags (Automatic Hold) + +Any of these flags should move a technology to Hold regardless of other scores: + +- **Single point of failure.** Core dependency managed by a single person or company without redundancy. +- **No clear governance.** Unclear licensing, governance model, or contribution process. +- **Security concerns.** Known unpatched vulnerabilities, history of supply-chain attacks. +- **EOL or deprecated.** No active development, community migration away. +- **License incompatibility.** License conflicts with company policy or distribution model. + +--- + +## Deprecation Policy + +Removing technology is harder than adding it. A clear deprecation policy prevents the accumulation of zombie technologies. + +### Deprecation Process + +1. **Announce intent.** "We plan to deprecate Technology X. Here's why, and here's the migration path." +2. **Freeze new usage.** No new projects may adopt the deprecated technology. +3. **Provide migration window.** 3-12 months depending on complexity. +4. **Support during migration.** Documentation, office hours, migration tools. +5. **Sunset date.** After this date, no support, no security patches, no guarantees. +6. **Archive.** Final documentation archived. Technology removed from radar. + +### Deprecation by Volume + +| Scenario | Migration Window | Support Level | +|----------|-----------------|---------------| +| <5 consumers | 3 months | Documentation only | +| 5-20 consumers | 6 months | Dedicated migration guide + office hours | +| 20-100 consumers | 9-12 months | Migration tools, paired support, extended support | +| 100+ consumers | 12+ months | Automated migration, phased approach, extended support | + +### Pitfalls + +- **Deprecation without migration path.** You cannot remove a technology without showing people what to replace it with. "Don't use X anymore" without "use Y instead" creates chaos. +- **Too many holds without removal.** If technologies sit on Hold indefinitely, the Hold ring loses meaning. Set sunset dates for every Hold decision. +- **Ignoring the migration cost.** For deeply embedded technologies (e.g., a database, a framework), the migration cost may exceed the benefit of deprecation. Be honest about the economics.