Part 4: Skills as load-bearing SDLC roles

[#1]

---

The last article ended on a dispatch. The intake gate reads the item's status, decides what work is legitimate, and — if the request is legitimate — hands the invocation off to a phase-specific skill: refinement, readiness evaluation, development, review. Each of those skills is the subject of this article — specifically, what they have to be to actually work.

The short version is that they're the roles themselves.

What "role" means in a human team

Many of the software teams I've been on, someone was the requirements analyst. Sometimes formally (a job title, a person hired for it), sometimes “tacitly” (the tech lead who quietly rewrote everything after standup, the PM who doesn’t mind a bit of overreach). Someone was the reviewer. Someone was the developer. Someone signed off. The roles were real, even when nobody had written them down, because human beings are pretty good at inferring "I'm the one who does this" from a mixture of temperament, seniority, availability, and habit.

For a human team, the role and the person are inseparable. Brian is the analyst; he has opinions about scope, a mental model of the codebase, and a bar for readiness he calibrated over three years. When you ask Brian to refine a ticket, you get Brian’s refinement — and that's exactly what you wanted. The role sits in the person: it arrives with them, and it leaves with them. This is why it holds together: the process is the skeleton, but the people are the muscle.

Try to apply that logic to an agent and it collapses. The agent is not Brian. It doesn't have three years of context, or a bar it calibrated, or opinions about scope. And the agent invoked to refine one ticket may or may not be the same agent invoked to review the next one. From the system's point of view they might be the same model with different skills loaded, or different models entirely, or the same agent on different days after a minor prompt tweak. The role can't live in the person, because the person is swappable and the role isn't.

So the role has to sit somewhere else. It has to sit in a file.

The move: the role is what the agent puts on

For an agentic team, the SDLC roles stop being things people are and become things that are written down. Each role becomes a discrete artefact with its own authority, its own exit conditions, and its own contract for handoff. In this project that artefact is a skill file, but the format doesn't matter. The agent is not the analyst. The agent loads the analyst skill when the gate dispatches to it, and while that skill is loaded, the agent behaves as the analyst behaves: same authority, same standards, same outputs, same refusals.

Put differently: the role is what the agent puts on, not who the agent is.

The doorman from the last article doesn't become a specialist when he shows you to one. He hands you over. The agent does the same thing to itself: it stops being a general-purpose reader of the ticket and picks up the analyst's file, and for the duration of that invocation there is no difference between it and the analyst.

It means:

• The role is versionable. If the readiness bar changes, you change one file. Every agent that loads it thereafter uses the new bar. You don't have to retrain a team.

• The role is auditable. An item was approved six months ago against a bar that has since moved. You can go and read the bar as it stood on the day — it's a file, and git log has every version of it.

• The role is substitutable. Any capable model that loads the analyst skill is the analyst for the duration of that invocation. There is no "senior analyst tacit knowledge" hiding somewhere; if it existed, it would be in the file.

• The role is enforceable. The workflow can require that the readiness reviewer produce a Readiness: READY marker with six named sections before advancing the item. It cannot require Brian to notice something in his gut.

The upside is huge. The cost is that everything the role does has to actually be in the file. There is no substrate to fall back on — the shared, unwritten understanding the first article was about is exactly what an agent doesn't have. Every judgement the role makes, every decision it may take vs. escalate, every output it produces — has to be describable in a document a new agent can pick up cold and execute.

Delete the file and the role ceases to exist on the team, no matter how many agents you have.

What a skill file has to contain to be a role

Every one of these is a question a new starter asks in their first week, and a good manager answers without being asked twice. When do I pick something up? What can I decide on my own? What do I have to produce? When am I done? The difference is that a new starter who doesn't get answers will ask, or copy the person next to them, or quietly work it out over a month. An agent invoked cold does none of those things. It guesses, once, confidently, and moves on.

So not every markdown file counts. A skill file that is really the role has to answer four questions, unambiguously, in a document short enough for the agent to reliably load and follow:

1. When does this role start? The status the item must be in, the evidence that must already exist, and the transition that claims it. An analyst skill that says "load me when the item needs refining" doesn't have an entry condition; it has a hope. An entry condition is Awaiting Refinement, unclaimed, and the claim transition fires first.

2. What may this role decide? What it can write, edit and transition on its own, and what it must escalate instead of resolving.

3. What must this role produce? The marker comment it posts, the sections that comment must contain, and the structural evidence that has to exist before it hands off.

4. How does this role end? Every outcome it can reach, the transition that fires for each, and when it unclaims rather than advancing. A role with one exit (finish and move on) is not yet a role. This one has a name in the design doc, like the numbered principles in the earlier articles:

P3. Every phase has the same three kinds of outcome: forward, back, unclaim.

Three kinds, note, not three outcomes. "Back" is a kind, not a single destination. The code reviewer has two ways of sending an item back — the code can be wrong, or the specification can be — and those go to different places. So it needs four markers to express three kinds. Article 6 is about why those two have to be different destinations.

If a skill file can answer those four questions crisply, it's a role. If it can't, it's documentation about a role — and the agent, invoked cold, will treat it as advice rather than contract.

The self-contained rule

There's a specific property of skill files worth calling out, because it's easy to miss until it burns you. Skills, in the platforms I've used to build this project (Claude Code, Rovo Dev, GitHub Copilot), auto-load by description-match: the agent picks up a skill because its description sounds relevant to the current task. Sometimes multiple skills load; sometimes only one; sometimes — critically — the one you thought would load doesn't.

The description field is not documentation — it's the matcher. A skill called jira-review described as "the review phase" will be picked up for a code review, a design review and a performance review, because nothing in that sentence says which. The descriptions that work name the trigger conditions rather than the subject: use when an item is in Awaiting Review, after intake has cleared you. You are not summarising the file. You are writing the condition under which it should win.

The next rule follows from that matching behaviour: every skill has to stand alone. (The obvious response — then put everything in one skill and stop worrying about it — is the right question to ask, and it has a section of its own further down. It turns out to be the one shape that breaks the whole thing.) If the review skill relies on the reader having already loaded the documentation skill, the review skill is unreliable — because the documentation skill may not have loaded, and the reviewer will silently miss whatever it was going to inherit.

This produces one writing discipline worth naming. Every convention a skill depends on has to be restated in it, or pointed at so cleanly that the agent follows the pointer — even when that convention is written somewhere else.

This is one of those places where the platform's ergonomics push you towards a good habit. Skill files should be dense but complete. It is better for two skills to repeat a convention verbatim than for one to rely on the other having loaded. Watch for the phrase "as covered in the other skill". It means one of two things needs to happen: either inline the coverage, or point at the file by path and say load this before proceeding. What it must never mean is "the reader will have it already."

The four roles and the eleven files

Sorted by what each file is for, a familiar shape emerges — Analysis, Development, Quality Assurance, plus the standards and conventions everyone works to.

A skill file is just a document an agent loads on demand. Some of them are roles. The rest are the things roles need — the standards they judge by, the conventions they write in, the manuals they consult. A role is a kind of skill, not a synonym for one.

The current inventory:

• The phase-generic gate. jira-work-intake — the doorman from the last article. Not a role in the SDLC sense; a preface every role's invocation begins with.

• The requirements analyst. jira-refinement — the author of the specification. Entered from Awaiting Refinement, produces a shaped item with acceptance criteria, exits either to readiness evaluation or back to the backlog depending on whether the item has been committed to.

• The readiness reviewer, and the two files it judges by. jira-readiness — the analyst's auditor: a different role from the analyst, because one authors the spec and one audits it, and article 6 will make the case for why that separation is load-bearing rather than stylistic. It judges by two further files: definition-of-ready for how good an item has to be, and design-fit-check for whether the work fits the architecture. The role says what the auditor may do; those two say what "good" means.

• The developer. jira-development — implements against the specification the reviewer approved. Entered from Awaiting Development with a Readiness: READY marker; exits to review with a Development: COMPLETE marker of its own.

• The code reviewer. jira-code-review — audits the PR against the acceptance criteria, not against the developer's own completion comment. It's the phase that needs a fourth marker: an item can come back because the code is wrong, or because the specification was, and those go to different places. Article 6 is about why.

• The shared writing contracts. jira-conventions and jira-documentation. These aren't SDLC roles; they're the mechanics-and-grammar layer every role writes into. jira-conventions carries the status-id-and-transition-id table and the label taxonomy; jira-documentation carries the description-zone anatomy, the marker-comment grammar, and the acceptance-criteria format. Every role skill relies on these existing, and per the self-contained rule, every role skill either inlines what it needs or points at the shared file by path.

• The codebase's operating manuals. project-commands and architecture-guide. These are the two skills that carry the code-side ergonomics — the exact commands to run, test, and serve anything; and the extension framework and API surface. They exist because the developer and reviewer roles both have to reach for concrete commands and concrete architectural constraints, and both should reach for the same source of truth rather than reinventing it in their own skill files. One admission here: they're pointed at from AGENTS.md rather than from the role skills that need them. In Claude Code that's harmless, because persistent instructions load on every invocation. It stops being harmless the moment a role runs somewhere those instructions don't — which, as the next section shows, is exactly what happened to the readiness reviewer.

Notice the shape:

1 gate	jira-work-intake
4 roles	jira-refinement	the analyst
	jira-readiness	the auditor
	jira-development	the developer
	jira-code-review	the code reviewer
2 standards	definition-of-ready	how good an item has to be
	design-fit-check	whether the work fits the architecture
2 contracts	jira-conventions	the workflow's mechanics
	jira-documentation	how anything written is written
2 manuals	project-commands	how to run and test the code
	architecture-guide	the architecture the code has

Eleven files, one workflow. Four of them are roles; the other seven are things the roles share.

The reason to arrange them this way — rather than as one giant skill per agent, or one skill per phase with everything embedded — is the same reason you separate concerns in code: each thing changes on a different schedule, each has a different owner, each is easier to reason about alone than in combination. When the readiness bar shifts, definition-of-ready moves and the readiness reviewer's own file doesn't. When the architecture grows a new component, the file describing the architecture moves and none of the SDLC skills notice. When a new phase gets added, you add a skill; the other ten stay where they are.

That's the design. Here's where the implementation didn't match it.

The role that lived in the wrong place

Here is one I got wrong, and only noticed while writing this article.

For most of this project's life, three of the four roles were skill files, and the readiness reviewer wasn't. Its instructions lived in a loose file instead — never built to the same pattern as its siblings. The role still worked; it still had a bar to enforce and a job to do. It just wasn't a skill.

That's a consistency gap, not a missing capability, and it's worth being precise about what it cost. Every property a skill file buys — versionable, auditable, substitutable, enforceable — is a property this role went without, for no better reason than that nobody had gotten around to building it the way the other three were built.

Fixing it wasn't a redesign. It was bringing an outlier back in line with a pattern already proven to work: give the readiness reviewer a skill file like the other three, and it inherits everything they already have.

A pattern only pays off once every role is actually built to it. An outlier that isn't yet a skill doesn't get exempted from the benefits skills provide — it just quietly goes without them, until someone notices and closes the gap.

The temptation of the super-skill

Anyone who builds this will eventually consider the super-skill: one big file — how to be a good software engineering agent on this project — instead of eleven small ones. It's almost always wrong, and it's worth knowing why, because the reasoning is not the obvious one. It'll be internally consistent. It'll never miss a shared convention because it never split into pieces. And it'll load reliably on every invocation, because the description will match anything.

The problem is that a super-skill can't refuse. If the same skill contains the analyst's authority and the developer's authority, an agent that reads the skill will believe it has both, and the workflow's most important property — the analyst isn't the developer; neither is the reviewer — collapses on contact with any invocation that hasn't already routed itself correctly. The gate can no longer dispatch, because there's nothing distinct to dispatch to. Every phase's outputs become theoretically available at every phase's input. You've reinvented substrate, only now it lives in a single 12,000-line file, and you're relying on the agent to notice which paragraph of it applies today.

The self-contained rule is not "put everything in one file so nothing is missed". It's "make sure each role's file stands up on its own". Those are opposite disciplines. The first produces roles that can't tell each other apart; the second produces roles that can't be confused.

What this buys you

All of this — four SDLC roles as files instead of one clever agent — makes the parts swappable. If a different platform's agent has to pick the work up mid-flight, it can, because everything the previous agent was doing is either in the item, in the file, or in the codebase — never in the model's head.

That is what "load-bearing" means for these skills: they're not just documentation about how the agents should behave. They are the behaviour.

Try this before the next article

Pick the role your team's agent is implicitly playing today. Not the one you'd wish it played — the one it actually does, based on how it's most often invoked. Then write down, in half a page or less, its answers to the four questions:

1. When does this role start?

2. What may this role decide?

3. What must this role produce?

4. How does this role end?

Half a page is a lot. Don't panic if the first pass has gaps. Every gap is a place where the substrate was doing the work — the same substrate the last three articles have been about — and every gap is the same class of failure as the ones the earlier articles described. Naming them is the first step; deciding what the file should say about them is the next.

You don't need a skills platform to do this. You need a file, and the discipline of treating it as the role.

---

Next: The three-tier authority model. How an agent, mid-invocation, decides whether to answer a question silently, decide-and-record it, or escalate to a human — and why the tier the question falls into matters more than the question itself.

---

A note on how this was made

Every idea in my writing comes from real work — built, broken, and figured out before a single word is written. The writing is documentation, not speculation. I start with voice dictation: a raw thought dump of ideas, objectives, and what I've actually been working on. From there, I collaborate with AI to shape that into something readable — structuring drafts and editing through a custom Rovo agent, configured with carefully curated instructions to review and refine work against my preferences, personality, and style. Artwork is a separate creative process — concepts originate from my own ideas and are brought to life using a combination of Google Gemini, ChatGPT, and Photoshop. The ideas, the experience, the creative direction — those are mine. AI is how I move fast and bring them to life.

Before anything is published, every claim and every idea goes through multiple review cycles to make sure it accurately reflects the thoughts and experience I originally set out to convey. If something reads well, that's the process working. If something doesn't, that's on me.