4 posts tagged with "productivity"

Meta Description: Matt Pocock's "skills" repo hit 26K+ stars in days — a curated set of agent skills for planning, TDD, refactoring, and architecture. Here's what it means for real engineering workflows.

The Problem: AI Agents That Don't Think Like Engineers​

Most AI coding assistants fall into the same trap. You describe what you want, and they immediately start writing code. No planning. No questioning. No validation. It's "vibe coding" — and it produces the kind of software that looks right but falls apart under pressure.

Matt Pocock — the TypeScript educator behind Total TypeScript — dropped an open-source repo this week that takes a fundamentally different approach. Called simply skills, it's a collection of reusable agent skills designed for real engineering, not casual code generation.

The repo gained over 26,000 stars in its first week. That's not hype — that's developers recognizing a missing layer in their AI workflows.

What Are Agent Skills?​

If you've used Claude Code, you know about .claude directories — configuration files that shape how the AI agent behaves in your project. Skills take this further. They're self-contained instruction sets that give an AI agent a specific workflow, not just knowledge.

Think of it this way: a system prompt tells an agent what it knows. A skill tells an agent what to do — step by step, with guardrails, in a repeatable way.

Matt Pocock's collection targets the phases of development where most AI tools fall short: planning before code, structured refactoring, and disciplined testing.

The Planning & Design Skills (Think Before You Code)​

This is where the collection shines brightest. These five skills force the agent to slow down and think:

• to-prd — Takes your conversation context and synthesizes it into a proper Product Requirements Document, filed as a GitHub issue. No back-and-forth interview. The agent reads what you've already discussed and writes the spec.

• to-issues — Breaks a PRD or plan into independently grabbable GitHub issues, sliced vertically (each one delivers user value on its own). This alone solves one of the biggest problems in AI-assisted development: the agent tries to do everything at once.

• grill-me — The agent relentlessly interviews you about your plan or design. It doesn't stop until every branch of the decision tree is resolved. It's like having a senior engineer who won't let you merge until you've answered all the hard questions.

• design-an-interface — Generates multiple radically different interface designs for a module using parallel sub-agents. Instead of the first idea that comes to mind, you get options to compare.

• request-refactor-plan — Walks you through a refactor via interview, creates a detailed plan with tiny commits, and files it as a GitHub issue. The plan itself is valuable documentation.

The Development Skills (Code With Discipline)​

Once planning is done, these skills enforce engineering best practices:

• tdd — Test-driven development with a strict red-green-refactor loop. Features get built one vertical slice at a time. The agent writes a failing test, makes it pass, then refactors. This is how TDD is supposed to work, and most developers never do it manually. With an agent enforcing the loop, it actually happens.

• triage-issue — When a bug comes in, the agent explores the codebase, identifies the root cause, and files a GitHub issue with a TDD-based fix plan. No more rubber-ducking a stack trace alone at 2 AM.

• improve-codebase-architecture — The agent reads your CONTEXT.md and docs/adr/ (Architecture Decision Records) to find opportunities for deepening — making the codebase's structure better reflect its domain. It's like a periodic architecture review that actually produces action items.

Why This Matters for Engineering Teams​

The real insight here isn't any single skill. It's the philosophy: AI agents should enforce process, not skip it.

Here's what that looks like in practice:

1. You talk through an idea with your agent
2. to-prd captures it as a proper spec
3. grill-me stress-tests the spec
4. to-issues breaks it into grabbable work items
5. tdd implements each one with test-first discipline
6. triage-issue handles bugs the same way

Every step has structure. Every step produces artifacts (GitHub issues, test files, PRs) that persist beyond the conversation. The agent isn't just writing code — it's participating in your engineering workflow.

Getting Started​

Each skill installs with a single command:

npx skills@latest add mattpocock/skills/<skill-name>

They work with Claude Code out of the box. The npx skills CLI handles the setup — adding the skill's instructions to your .claude configuration.

If you're using other agent frameworks (like OpenClaw, Cursor, or Windsurf), the skills are just markdown files. You can read the source and adapt the patterns to your setup. The workflows are framework-agnostic; only the installation method changes.

The Bigger Picture: Agent Skills as Infrastructure​

This repo represents something larger than a collection of prompts. It's evidence that agent skills are becoming infrastructure — the same way linters, formatters, and CI pipelines became standard.

Consider the parallels:

• Prettier standardizes formatting. Everyone on the team writes code that looks the same.
• Husky + lint-staged enforces checks before commits. Nobody skips the linter.
• Agent skills standardize how AI participates in your process. The agent doesn't just generate — it follows a workflow.

As AI coding tools become ubiquitous, the teams that differentiate won't be the ones using AI the most. They'll be the ones using AI the most disciplined way. Skills are how you encode that discipline.

FAQ​

Q: Do these skills only work with Claude Code? A: They're designed for Claude Code's skill system, but the underlying patterns are markdown-based and framework-agnostic. You can adapt them for any AI coding assistant that supports custom instructions.

Q: Which skill should I start with? A: Start with grill-me. It's the fastest way to see the difference between "AI that writes code" and "AI that thinks through problems." Run it on any design decision you're currently wrestling with.

Q: Are agent skills the same as custom system prompts? A: No. A system prompt sets context and personality. A skill defines a repeatable multi-step workflow with specific inputs, outputs, and guardrails. It's closer to a CI pipeline than a prompt.

Q: Can I create my own skills? A: Yes — the repo includes a write-a-skill skill that teaches the pattern. Matt Pocock also runs a newsletter at aihero.dev where he shares new skills and updates.

Overthinking doesn't look like procrastination. It looks like productivity. You're researching, reading, exploring prior art, comparing tools. It feels like work — because technically it is. But your project isn't moving forward. The code isn't shipping. And by the time you realize what's happening, you've spent hours (or weeks) going nowhere.

Kevin Lynagh, a software engineer and toolsmith, wrote a brilliant essay on this exact trap. His diagnosis is sharp: the root cause isn't laziness or lack of skill — it's unclear success criteria combined with an instinct to research before building.

This article breaks down why overthinking and scope creep are the silent killers of software projects, and what you can actually do about it.

The Two Outcomes of Every Project Idea​

Every project idea tends to go one of two ways:

1. You just do it. You build it, make minor revisions, and it turns out roughly how you imagined. You ship. You're done.
2. You start researching. You look for prior art. There's a lot of it. The scope broadens. You start wondering if you should build on top of existing solutions. Or maybe you should just use the popular thing. But you could do better, if you invested more time. But you don't want to maintain something big. And now you've spent hours without shipping anything — or experiencing the joy of creating something.

Outcome #1 is obviously better. The question is: what determines which path you take?

Fuzzy Success Criteria Is the Root Cause​

The pivotal factor is how well you've internalized your success criteria before you start.

When Lynagh wanted to build a kitchen shelf with a friend, the success criteria was crystal clear: make a shelf for my exact kitchen, and have fun doing woodworking with a friend. Done in a weekend. No overthinking.

But when he went down a rabbit hole researching structural diffing tools, he spent four hours reading about PhD-level tree diffing algorithms before remembering his actual goal: build a nicer diffing workflow for myself in Emacs. Estimated time: four hours. He spent those four hours researching instead of building.

The pattern is clear: fuzzy goals invite scope creep. When you can't articulate exactly what "done" looks like, your brain fills the void with more research, more comparison, more planning.

This is especially dangerous for founders and indie developers who wear multiple hats. You don't have a product manager telling you to stop researching and start shipping. You are the scope creep.

The Conservation of Scope Creep​

Here's a particularly painful observation from Lynagh's essay: when he used an LLM to help build a fuzzy file search tool, the LLM found a great library (Nucleo) that had extra functionality — anchor-based matching. This triggered a chain of "what if" questions:

• What if anchors worked differently for file paths?
• What if we anchored to path segments instead of lines?
• What about handling slashes in anchored queries?

Several hours of design work and code later, he realized: he had never once wished his original tool had anchor functionality. He threw it all out.

This is what Lynagh calls a "conservation law" of software development: any increase in programming speed (from AI tools, better libraries, faster languages) will be offset by a corresponding increase in unnecessary features, rabbit holes, and diversions.

The LLM didn't cause the scope creep. But it accelerated it. Faster code generation means you can go down rabbit holes faster — and dig yourself deeper before realizing you should have stopped.

Why Smart People Are the Most Vulnerable​

There's a painful irony here: the people most susceptible to overthinking-driven scope creep are often the most capable engineers.

Why? Because they can see the broader implications. They can imagine the edge cases. They can design elegant abstractions. And all of that capability becomes a liability when it's deployed against a problem that just needed a simple, direct solution.

Lynagh describes his own long-running interests — designing a programming language that fuses Clojure and Rust, building interfaces for hardware prototyping, creating a CAD language — as being stuck in the research phase for hundreds of hours. He's learned a lot by reading. But he hasn't shipped.

His self-diagnosis: "My inner critic (fear of failure?) is silencing my generative tendencies, keeping me from the much more enjoyable (and productive!) learning by doing."

How to Actually Ship: Practical Anti-Overthinking Strategies​

1. Write Down Your Success Criteria Before Starting​

Not in your head. On paper. One to three sentences that define "done."

Example: "A CLI tool that diffs two files by function/class, showing added/removed/changed entities. Must work with TypeScript and Python. I use it myself in Emacs."

If you can't write it in three sentences, you don't have clear enough criteria yet. Don't start building until you can.

2. Apply the YAGNI Rule Aggressively​

"You Ain't Gonna Need It" isn't just a software design principle — it's a project survival strategy.

Every time you think "it would be nice if...", ask: "Do I have a concrete use case for this right now?" If the answer is no, skip it. You can always add it later. You can rarely undo the time spent building things nobody needed.

3. Set a Time Box​

Before starting, estimate how long the task should take if you scope it correctly. Then set a hard deadline. If you estimated four hours and you're two hours deep into researching alternatives, you've already failed the time box. Stop researching and start building.

4. Default to Building, Not Researching​

Research is valuable. But it has diminishing returns fast. The first 30 minutes of research will give you 80% of what you need. The next four hours will give you the remaining 20% — and probably introduce enough scope creep to kill the project entirely.

When in doubt, build first. You'll learn more from a working prototype than from reading ten blog posts about how other people solved similar problems.

5. Embrace the "Clueless 20-Year-Old" Mindset​

Lynagh's closing advice: embrace your inner clueless 20-year-old and just do things. Some will turn out "obviously bad" in hindsight. But you'll come out ahead on net — because the experience of building, failing, and iterating teaches you more than the experience of endlessly planning and never shipping.

This isn't about being reckless. It's about recognizing that the cost of a bad first version is almost always lower than the cost of never shipping.

The Real Cost of Overthinking​

Every hour spent researching instead of building is an hour you could have had a working prototype. Every feature added to the scope is a feature that delays the ship date. Every "what if" question that doesn't have a concrete user behind it is scope creep in disguise.

The projects that succeed aren't the ones with the most features or the most elegant architecture. They're the ones that shipped. That got into users' hands. That generated feedback and iteration data.

If you're building something — a startup, a side project, a tool for yourself — the single most impactful thing you can do today is clarify what "done" looks like, resist the urge to broaden the scope, and start building.

The enemy of shipped product isn't laziness. It's perfectionism in disguise.

FAQ​

Q: How do I know if I'm overthinking vs. doing necessary research? A: If your research has a clear stopping point tied to a specific decision, it's necessary. If you're "just browsing" or keep finding new rabbit holes, you're overthinking. Set a time limit: 30 minutes of research, then decide and move on.

Q: What's the difference between good scope and scope creep? A: Good scope addresses a real user need you can articulate in one sentence. Scope creep addresses a hypothetical need — "what if someone wants to..." — without a concrete use case behind it.

Q: How do AI coding assistants affect scope creep? A: They accelerate it. LLMs can generate scope creep faster than you can think through whether you actually need it. Be extra vigilant about success criteria when using AI tools — they'll happily build features you never asked for.

Q: Is overthinking always bad in software development? A: No. For infrastructure decisions, security architecture, and data model design, careful thinking is essential. The key is knowing which category your current task falls into. Most feature work and prototypes benefit from moving fast, not thinking deep.

About the Author​

Arkin is a startup founder and developer building Orbits Studio, a clip farming marketplace connecting everyday creators with brands. He writes about software engineering, startup lessons, and building in public.

Meta Description: Most engineering teams don't know their true ROI. Here's why measuring software economics matters — and why it's harder than it looks.**

The $60,000 Question​

Here's a scenario that plays out in engineering organizations every day: Your team spends three weeks building a feature that serves 2% of your users. With a typical all-in engineering cost of €100,000 per year, that's roughly €60,000 of investment for a minority of your user base.

Was it worth it?

If you're like most engineering leaders, you don't know. You have a gut feeling. You have some usage metrics. You have a vague sense that "the sales team said they needed this." But you don't have a number — or even a method for generating one.

This is the core thesis of the discussion around software team economics: Most engineering organizations are flying blind when it comes to understanding the financial impact of their work.

The Optimization Trap​

The seductive argument goes like this: If every feature decision were made with clear ROI calculations, organizations would make better decisions. A €60,000 feature for 2% of users is easy to evaluate against a €60,000 feature for 20% of users. Armed with this data, engineering leaders could reallocate resources to high-impact work and eliminate waste.

There's truth to this. In the zero-interest-rate era, companies hired aggressively, shipped aggressively, and worried about efficiency later. That era is over. Companies that can't connect engineering output to business outcomes are in trouble.

But there's a trap here.

What Gets Measured Gets Managed (And Sometimes Broken)​

The first problem is attribution. Software doesn't exist in a vacuum. Your company ships 10 features in a quarter, revenue goes up $1M, and you land a new enterprise contract that uses all of them. How much of that revenue belongs to Feature #7?

Every team will attribute the entire win to themselves. The alternative — revenue that disappears without explanation — is politically unacceptable. So you end up with sum-of-parts greater than the whole, and metrics that no one trusts.

The second problem is the measurement burden. If every feature needs a dollar value attached, who does the calculation? Product managers become analysts. Engineers spend time setting up measurement baselines for work that hasn't shipped yet. The meta-work of justifying work starts to rival the work itself.

The third problem is the most insidious: innovation doesn't have a clear ROI when you start.

The Innovation Paradox​

WhatsApp was built by 30 engineers serving 1 billion users. But WhatsApp in 2010 didn't have 1 billion users. It had a few thousand. At what point in that journey did the feature work of those 30 engineers become "worth it"?

If you measured strictly by short-term ROI at every step, you might have killed the project six months in. The features that matter now — end-to-end encryption, cross-platform sync, minimal data collection — were long-term bets that looked like waste when they were built.

This is the paradox: The most valuable engineering work often looks like waste until it becomes indispensable.

The Missing Layer: Baseline Before Optimization​

There's a sensible middle ground that gets lost in the "bean counters vs. pampered artists" framing.

The problem isn't measurement itself. The problem is measuring without baselines. Consider a DevOps engineer who automates a manual task that cost every developer 2 hours per week. That's 80 hours saved per week for a 40-person team. But what do those engineers do with the extra time?

If they use it to ship more features, the ROI is clear. If they take longer lunches, the ROI is zero. The difference isn't about the automation — it's about whether the freed-up capacity has a place to go.

As one commenter put it: "Profile before you optimize and the return on investment calculates itself." Most organizations skip the profiling step. They don't measure what happens now, so they can't measure what happens after.

The 3-5x Rule​

There's a rule of thumb that circulates in engineering leadership: A feature needs a 3-5x return on investment to be worth building. The math is simple: Building a feature costs €60,000. If it generates less than €180,000 of value, you're losing money.

But here's what this rule misses:

1. Lifetime value vs. first-year value. A feature might cost €60,000 to build but generate €20,000 annually for five years. That's a 4x return, but if you measure strictly in year one, it looks like a failure.

2. Capability building, not just features. Some work doesn't generate revenue directly but enables revenue-generating work. Infrastructure platforms, developer tooling, security hardening — these are investments in capability.

3. Option value. A feature for 2% of users might unlock an adjacent market segment. That 2% might be a beachhead for a much larger opportunity.

The Role of AI in All This​

The original discussion that sparked this thread included a provocative claim: AI agents can replace much of what engineering teams do today, at lower cost, with different trade-offs.

The counter-arguments were equally strong: AI-generated code becomes unmanageable technical debt. Agents can't reason through unfamiliar systems at scale. You still need a human to fire and sue.

But the deeper question isn't "Will AI replace engineers?" It's: "How does AI change the economics of software production?"

If AI can ship a 95% clone of Slack in two weeks (as the original article claimed), what does that mean for teams spending years building products from scratch? The value of engineering has always been more than lines of code per hour. But as the cost of code drops, the value of everything else — product judgment, user empathy, strategic thinking — rises.

What Actually Matters​

Here's what the most productive engineering teams actually do:

They focus on problems they care about. One commenter put it best: "The only thing that matters is whether the people on the team care deeply about the product." Teams that don't care have a productivity ceiling no amount of process can fix.

They build in increments. Shipping 10 major features in a quarter makes attribution impossible. Shipping one feature every week makes it clear what landed and what didn't.

They understand the business. Engineers who know how their company makes money — not just "we sell software" but "we sell to HR directors at 500-person companies with specific compliance needs" — make better decisions.

They accept uncertainty. Not every feature will succeed. Not every infrastructure investment will pay off. The goal isn't to eliminate uncertainty — it's to take calculated bets and learn from the results.

A Framework, Not a Formula​

Here's a practical framework for thinking about engineering economics, short of full financial modeling:

1. Measure the things you can. If you're building something, know the baseline. How long does this take now? How many users touch this? What's the current failure rate?

2. Know your multipliers. A €60,000 feature for 2% of users might be worth it if that 2% represents your highest-value customers. A €60,000 feature for 50% of users might be a waste if those users don't pay.

3. Distinguish between capability and output. Infrastructure that makes everyone 10% faster is different from a feature that drives direct revenue. Measure them differently.

4. Track learning, not just outcomes. Did a feature fail because the market wasn't there, or because the execution was wrong? That's valuable data either way.

5. Keep the meta-work minimal. If calculating ROI takes longer than building the feature, you're optimizing the wrong thing.

The Bottom Line​

Engineering organizations are flying blind — but maybe that's okay up to a point.

The extreme of no measurement is waste: teams working on things that don't matter for users who don't care, with no accountability for results.

The extreme of hyper-measurement is paralysis: every decision requires a business case, every feature needs a revenue forecast, every engineer becomes a part-time analyst.

The middle ground is pragmatic: Measure what you can, accept what you can't, focus on problems worth caring about, and trust that the outcomes will follow.

The €60,000 question isn't whether that feature for 2% of users was worth it. The question is: Did you learn something that makes the next decision better?

FAQ​

Q: How do I measure ROI for engineering work? A: Start with baselines. Measure before you change. For features, track adoption, retention, and revenue impact. For infrastructure, measure time saved, error reduction, or developer satisfaction. But accept that some value is unmeasurable — like team morale or strategic option value.

Q: What's the 3-5x rule for engineering ROI? A: It's a heuristic that a feature should generate 3-5x its cost to be worth building. If building costs €60,000, the feature should generate €180,000-€300,000 of value. But this rule misses long-term value, capability building, and option value — so use it as a filter, not a law.

Q: How does AI change software team economics? A: AI lowers the cost of code generation, which changes the relative value of engineering skills. As code becomes cheaper, product judgment, user empathy, and strategic thinking become more valuable. Teams should focus on what AI can't do: understanding problems deeply, making judgment calls, and building relationships with users.

Q: Should every feature need a business case? A: No. Hyper-measurement slows down innovation. A better approach: quick business cases for major bets, lightweight ROI tracking for routine features, and space for experimental work where the value is learning, not revenue.

About the Author: Arkin is a software engineer and startup founder building Orbits Studio. He writes about engineering economics, startup strategy, and the intersection of technology and business. Find him at arkin-dev.com.

You just joined a new team. Someone hands you a repo URL and says, "Get familiar with the codebase." What do you do?

Most developers start reading files from the top. They open src/, scroll through directories, and try to build a mental map folder by folder. That approach works—eventually—but it's slow, directionless, and leaves you guessing about the stuff that actually matters: where the problems live, who knows what, and whether the project is healthy or held together with duct tape.

Git has already been recording everything. Every bug fix, every refactor, every 3 AM hotfix—it's all sitting in the commit history, waiting to be read. You just need to know which questions to ask.

These five git commands take under two minutes to run and will tell you more about a codebase than a full day of browsing files.