boring-engineering

Build exactly what the current problem requires. No less, no more.

An AI agent skill that turns KISS, YAGNI, and practical DRY into a concrete decision system — so your coding agent stops overengineering by default.

---

The Problem

AI agents already know what KISS, YAGNI, and DRY mean. What they consistently fail at is knowing when to apply them.

Left alone, agents tend to:

• Add abstractions before there's a second use case
• Build plugin systems for features with one consumer
• Create BaseServiceFactory for a function that needs 10 lines
• Future-proof code for requirements that never arrive

boring-engineering fixes this by giving the agent a concrete 4-step decision system it runs before and during every implementation — not just a reminder to "keep it simple."

---

How It Works

The skill loads in three stages (Agent Skills progressive disclosure):

Stage 1 — Discovery (~100 tokens) At startup, the agent reads only the name and description from SKILL.md frontmatter. This is how it knows the skill exists without loading the full content.

Stage 2 — Activation When you ask the agent to implement, refactor, or review code, it recognises the task matches this skill and loads the full SKILL.md body into context.

Stage 3 — Deep Reference (on demand) If the agent needs to reason through a complex decision, it loads references/decision-framework.md or assets/decision-tree.md — only when the instructions point to them. These files never inflate context unnecessarily.

The 4-Step Decision System

Every time the agent writes or modifies code, it runs through:

Step 1 — Requirement Filter (YAGNI)
  Is this explicitly required? → NO: don't build it. YES: continue.

Step 2 — Reuse Check
  Does something already exist? → YES: reuse it. NO: continue.

Step 3 — Simplicity Check (KISS)
  What is the simplest correct solution? → Implement that.

Step 4 — Abstraction Check (Practical DRY)
  Is a new abstraction justified by proven repetition? → NO: keep it direct.

Full decision tree: assets/decision-tree.md Deep reasoning: references/decision-framework.md

---

Setup

Option 1 — Clone the repo

git clone https://github.com/alvindemesadev/boring-engineering.git

Then copy the skill into your agent's skills directory (see per-tool instructions below).

Option 2 — Copy just the SKILL.md

If you only want the core skill without the reference files:

curl -O https://raw.githubusercontent.com/alvindemesadev/boring-engineering/main/SKILL.md

---

Compatibility

This skill uses the Agent Skills open spec — a standard supported by 40+ tools as of 2026. One SKILL.md, any compatible agent.