implementation-lifecycle skill

Implementation Lifecycle

How implementation works in this method. This is the single umbrella skill: the framework (philosophy and decision logic) plus the No Loose Ends session discipline (how a session behaves around decisions — disposition of loose ends, when to ask, how to report). For procedural steps, see the specific skills referenced throughout.

"No loose ends" is this skill. When the user says anything about loose ends — "make sure there are no loose ends," "no loose ends on this one" — they mean the Session Discipline section below. The name describes the failure it prevents: the AI says it's done, then hands over a list of FYIs, caveats, and "worth noting" items that are all undispositioned loose ends.

If a session has drifted — FYIs and caveats piling up, stopping to ask questions with predictable answers, wrap-ups that promise future work instead of doing it — re-reading this skill is the way back on track. Everything below applies to every implementation session, whichever procedural skill is driving it.

---

The Four Entities

Every implementation area has up to four documents. They form a system. All of them colocate inside the PRD's directory, which lives under docs/prds/ (a program) or docs/changes/ (a bounded delivery — identical layout, identical handling; a directory in either root is what this skill means by "PRD") — see prd-writing-standards for the directory layout. The first three exist (or can exist) for every implementation area; phase documents exist only when the PRD has been split, but once they exist they are full entities, not scratch notes.

Entity	Purpose	Location
PRD	What we're building and why. Acceptance criteria. Scope.	docs/prds/{feature}/{feature}-prd.md
Technical Design	How we're building it. Data flows, mappings, integration points.	docs/prds/{feature}/technical-design.md
Assumptions Document	Business decisions we've proposed but haven't confirmed with stakeholders.	docs/prds/{feature}/assumptions.md
Phase Documents (when split)	Scope contract for one AI-session-sized slice of the PRD, plus the ledger of work routed into that phase from elsewhere. One file per phase at every depth; a phase that was split keeps its file as a short split record.	docs/prds/{feature}/phase-{id}-{short-name}.md — ids are positional (2, 2a, 2a1); phase-split owns the scheme

Paths above show docs/prds/; a docs/changes/ directory is identical.

Upstream of the PRD, when an idea was too big for one: an initiative brief and its PRD list in docs/initiatives/{name}/ (initiative-breakdown owns them). The initiative brief holds decisions that govern every PRD cut from it; the PRD list orders the planned PRDs. They are inputs to requirements work, not entities an implement session maintains. The one exception is the PRD list's Status column, which moves when a PRD is written and when its work reaches production. A requirements intake record in source-material/{name}/ (requirements-intake) is upstream of the PRD in the same way, whatever the size of the work: the stakeholders' decisions in their own words, drawn from raw material before the PRD was written, and never maintained by an implement session.

At the end of a split PRD, completion phases: phase documents delivery-audit or test-audit adds after every planned phase has closed, when a criterion turns out not fully built, marked **Added by delivery audit:** or **Added by test audit:** at the top, and feedback phases assumptions-document-feedback adds when stakeholder feedback changes or adds criteria after that point, or while every open planned phase is already being built, marked **Added by stakeholder feedback:**, and fix phases implement-from-discovery adds for a fix it was asked to build that is too big for one session, marked **Added by implement-from-discovery:**. phase-split owns their form ("Completion Phases"). They carry criteria the PRD states, never discovered work, and are never a destination for filed work.

Beside them, once a test audit has run: test-audit.md in the PRD's directory, the map of each criterion's test evidence. test-audit owns it, and only a test-audit session writes it; it is never a destination for discovered work.

PRD and Technical Design are the source of truth. Code implements what they say. If code and docs disagree, figure out which is right — fix the wrong one. Never implement something different from what the docs say without updating the docs first — and that includes ad hoc fixes to work delivered long ago: amending the PRD that owns the behavior is always allowed and is the cheapest thing a session can do. A change directory (prd-writing-standards, storage convention) is for work written up on its own, by the user's choice or by implement-from-discovery when a change it was asked to build is too big to amend or no PRD owns it (its Phase 4), never a way around an amendment. When a later PRD or change directory changes behavior an earlier one defined, the later one owns it and the earlier one is not rewritten (see "When Later Work Changes Earlier Requirements" below).

Assumptions Document is a green light. A declared assumption means "we're going with this unless stakeholders tell us otherwise." It does NOT mean "we're waiting for confirmation." The whole point is to keep moving. That is not a rule with exceptions — it is what an assumption is — and it holds for an entry that reopens a ruling a stakeholder already gave (Gate 3 in assumptions-document-writing): the build proceeds on the better-evidenced answer; what a reopened entry owes is louder disclosure, not a hold. When adding assumptions, always use the assumptions-document-writing skill — assumptions have a specific format (proposed answer, rationale, confidence, impact, confirm-or-correct checkboxes) and they consistently get written incorrectly without referencing that skill.

Phase Documents are born thin and grow into ledgers. At creation (phase-split), a phase doc is a thin scope overlay — AC labels, dependencies, a summary. Over the project's life it legitimately accumulates the work routed into it: "Carried forward from Phase N" / "Inherited from Phase N" sections carrying items discovered in other phases, each with enough context for the implementing session to execute without the originating chat's history. That growth is the system working as designed, because a future phase doc is the preferred landing place for discovered follow-up work that survives the Materiality Gate (see Session Discipline below — most discoveries dismiss instead) — it's the one destination with an automatic trigger: implement-from-requirements loads the doc when the phase is built. Nothing automatically comes back for a ticket in whatever the org uses to schedule work. The one kind of growth that stays forbidden is duplication — a phase doc never restates PRD acceptance criteria or Technical Design content; it carries routed work, not copied requirements.

Blockers are surfaced, never filed away. A blocker is material by definition, so it goes to bucket 3 — surface it to the user now, with the blocked work recorded in the governing PRD/phase doc so the continuation sees it (and any durable design fact the blocker revealed folded into the Technical Design). Whatever the org uses to schedule work sits outside this methodology — a ticket is fine as bookkeeping, but it is not a disposition on its own: nothing triggers a future session to go look there, so work inside the current PRD must still be carried by its governing doc.

---

Core Philosophy

Implementation Is Cheap

With AI, implementing is fast. If an assumption turns out to be wrong, we re-implement. The cost of backtracking is low. The cost of waiting for business decisions is high. We never block on stakeholder feedback.

Don't Stop to Ask — Decide and Proceed

When you encounter uncertainty, the answer is almost never "stop and ask the user." If you've done thorough investigation and have a proposed answer, you have everything you need to proceed, whatever its confidence. If it's a business question, declare it as an assumption; either way, implement it.

This applies even when the question is well-framed with clear options. Presenting the user with "Option A, B, or C — which do you prefer?" is still stopping and waiting. If your investigation points to option A with good reasoning, pick option A, document it as an assumption, and implement. The user validates asynchronously — not in the middle of your implementation flow.

The only time you stop and ask is when you cannot put forward an answer at all: the evidence favors none of the options over the others (in practice, a best answer under roughly 20%). A weak best guess is still a guess — it gets declared at its honest confidence, and the work proceeds on it.

The workflow when uncertainty arises:

1. Investigate first — read code, query databases, check APIs, search meeting notes and emails if the team keeps an archive, read documentation, write exploration scripts. Can you self-resolve to 95%+?
2. Once investigation stops raising your confidence — you're done deliberating. Pick your best answer at whatever confidence it has; if it's a business question below 95%, document it as an assumption; implement it.
3. If you cannot put forward an answer at all — the evidence favors none of the options — stop and ask. Name the options and what would decide between them. This is rare.

Stakeholders validate assumptions asynchronously. We correct course if they say we're wrong. But we don't wait.

Docs Before Code

Before changing code, align the documents:

• Docs right, code wrong → fix the code; when the code consistently does something else instead, first apply "When Later Work Changes Earlier Requirements" below: shipped behavior someone could have chosen is not reverted to match a document without a decision
• Code right, docs wrong → fix the docs first, then code is already correct
• Neither clearly right → resolve through investigation or assumption, update docs, then implement

Use the writing standards skills (prd-writing-standards, technical-design-writing-standards, assumptions-document-writing) when updating documents.

---

Confidence Thresholds

Confidence levels drive what action to take. These thresholds appear across multiple skills — here's the unified view.

Confidence	What It Means	Action
95%+	You're sure enough.	Just do it, whatever the impact. No need to disclose or ask. Don't fatigue stakeholders with things you're confident about.
Below 95%	Some uncertainty, slight to large.	Research more first. Exhaust investigation avenues — database queries, API tests, codebase analysis, meeting-note searches, web documentation, exploration scripts (scripts/exploration/). If still below 95% after research, put forward your best answer at the confidence it has, document it as an assumption using the assumptions-document-writing skill, and implement — at 30% as much as at 90%. Do NOT stop and present options to the user.
No answer to put forward	The evidence favors none of the options — in practice, a best answer under roughly 20%.	Stop and ask: a Blocking Open Question (assumptions-document-writing) naming the options and what would decide between them. Rare.

That table is the shared spine; the operative gate is two-tiered. Which tier applies depends on whether the question is technical or business — the distinction defined in the next section. This is the gate the implement skills actually run, and the one the Session Discipline section below refers to as "the confidence gates":

Question type	Proceed on your own	Declare a formal assumption	Stop and ask
Technical	A build choice: proceed on your best answer at whatever confidence, recording it in the Technical Design (or the commit message for a small one) with its reasoning. A fact: investigate until it is settled, at 90% or more	Only for a fact the build relies on that investigation could not reach, with the blocker named: a technical assumption in the register's Technical Assumptions section (assumptions-document-writing, "Sort Every Entry by What Would Settle It")	Only when no answer can be put forward, after investigation
Business	95%+, whatever the impact	Below 95% — a formal entry via assumptions-document-writing at its honest confidence, for asynchronous stakeholder validation	Only when no answer can be put forward

Both tiers share one stop: no answer the evidence favors. Anything short of that proceeds.

Technical vs Business Uncertainty

Not all uncertainty is the same. How you handle it depends on what kind of question it is.

Technical questions — about data characteristics, API behavior, field values, system constraints. These can almost always be self-resolved through investigation: query the database, test the API, read the code, write an exploration script or a temporary program. Keep doing homework until the question is answered — more investigation nearly always gets there. The safety rule for that probing: investigate in dev and sandbox environments; read production only read-only, only when nothing else can answer the question, and only where the project allows it (engineering-principles, "Production Data"); never write to production. Technical questions should rarely become formal assumptions — if you're about to add a technical assumption, ask yourself: "Could I answer this with a database query, an API call, or a quick throwaway script?" If yes, do that instead. A choice between workable ways to build it is never an assumption: decide it and record it in the Technical Design with its reasoning. What remains is a fact the investigation could not reach, because of missing access, data not loaded yet, or behavior only production shows; declare it as a technical assumption naming that blocker, never as a business one. It's still yours to confirm: retry it whenever the blocker may have cleared rather than leaving it hanging.

Business logic questions — about what the business wants, how users expect things to work, what the correct policy is. These cannot be self-confirmed — no amount of investigation tells you what the business intends. They are what the assumption mechanism exists for: propose the best answer, declare it, proceed, and route it to a stakeholder for validation. But check first: sometimes what looks like a business decision actually depends on a technical fact you can verify. Resolve the technical fact first — the business decision often becomes obvious once you know the data.

Example: "Should we include deactivated accounts?" sounds like a business question. But if the PRD says "import all historical user records for audit trail purposes," and deactivated accounts are historical records, the business decision is already made — you just need to verify the technical path for importing them.

The Key Insight

The goal is always to raise confidence through investigation, not to immediately declare assumptions. Assumptions are for when you've done your homework and genuine uncertainty remains — not a shortcut to skip research.

But once you've done that homework, proceed. If you've thoroughly investigated and have a best answer, you are not blocked, whatever its confidence. Document it as an assumption if it's a business question, and implement. The user does not need to be consulted — that's the entire point of this framework. Presenting well-researched options and asking the user to pick one is the same as blocking on a business decision, which is exactly what this framework is designed to avoid.

---

Decision Flow During Implementation

This flow is for questions the current work needs answered in order to proceed. A mid-implementation discovery is not automatically such a question — it first passes the Materiality Gate (Session Discipline below), and a dismissed observation never enters this flow or its investigation loop.

When you encounter a question or gap while implementing:

Question arises
    │
    ├─ Is this already in the assumptions document?
    │   └─ Yes → Treat it as decided. Implement per the proposed answer. Done.
    │
    ├─ Can I self-resolve through investigation?
    │   ├─ Yes → Investigate. If confidence reaches 95%+, just proceed. Done.
    │   └─ Partially → Investigate to raise confidence as high as possible.
    │
    ├─ After investigation, can I put forward a best answer?
    │   ├─ Yes, at any confidence → Pick it. If it's a BUSINESS question, declare an
    │   │        assumption (use the assumptions-document-writing skill). A build
    │   │        choice needs none — record it in the design or commit message. A
    │   │        fact investigation could not reach is a TECHNICAL assumption,
    │   │        naming its blocker. Implement. Do NOT present options to the user.
    │   └─ No — the evidence favors no option → Stop. Ask the user, naming the
    │            options and what would decide between them.
    │
    └─ Note: "I have a well-researched question with 3 clear options and I lean
       toward option A" means you have a best answer.
       Pick option A, proceed on it, implement it.

Already-captured assumptions are decided. Don't re-raise them, don't wait for validation, don't defer. The assumption process exists so we can keep moving. If an assumption is later found wrong, we'll re-implement — that's the designed workflow.

---