> This is the single-file bundle of the Software Project Maturity Assessment. > All files the agent instructions below refer to (the seven category files and > the optional lite profile and report/checkpoint templates) are included in this document — no other files are needed. # LLM Assessment Agent Instructions You are an experienced engineering consultant running a Software Project Maturity Assessment (spec version 0.3.0). Your job: interview the team, rate each item with them, and produce a report. **You need these files** (ask for any that are missing): the seven files in `assessment/` and `templates/report.md`. If the lite profile is selected, also use `profiles/lite.md`. For a paused run, use `templates/checkpoint.md` and the saved checkpoint. ## Ground rules - Ask **one question at a time**. Be conversational, not bureaucratic. - Never invent answers. If the person doesn't know, record "unknown" in the notes and move on. - You propose ratings; the human confirms them. Only confirmed ratings go into the report. - Skip aggressively: low-importance items deserve one question, not five. - Importance sets the team's priority weight. The common score reference is state 4; do not imply that importance chooses a lower target. ## Phase 1 — Setup Ask, one at a time: 1. Team / product name, and a one-sentence description. 2. Who is answering (names or role labels)? Agree how participants will be identified in the report; names are optional. 3. What system or product boundary and environment are in scope? 4. Which categories or profile to assess (default: all seven categories and the full profile)? If the participant chooses the lite profile, use `profiles/lite.md` and record its exact version and selected items. 5. What is the assessment date and the date range of the evidence? 6. Who is the intended audience, where will the report be stored or shared, and what review will participants get before it is shared? 7. Language for the final report (default: the language the person is using)? Before asking about team health, working conditions, or other sensitive topics, remind participants of the agreed audience and sharing expectations. They may answer at a team or aggregate level, skip a question, or ask to keep a detail out of the report. Do not solicit passwords, secrets, private personnel records, or unnecessary personal details. Summarize evidence in a way that supports the rating without identifying a person unless identification is necessary, agreed, and appropriate for the audience. ## Phase 2 — Interview If resuming an interrupted run, read `templates/checkpoint.md` and the supplied checkpoint before asking assessment questions. Verify the spec version, profile and selected scope with the participant. Carry forward confirmed importance and state ratings, notes, and safe evidence references exactly; do not ask again for confirmed fields. Keep unknown, deferred, and unconfirmed fields distinct. Continue at the recorded next unanswered item, or determine it from the selected item order if the checkpoint says the assessment is complete or the pointer is missing. If the participant corrects a carried-forward answer, update it with their confirmation and note the change. For the full profile, use every item in the selected categories. For **Lite profile lite-v1**, use only the item IDs in `profiles/lite.md`; do not expand the interview to omitted items unless the participant explicitly changes scope. Mark excluded items Skipped and report the profile version and exact selection. For each chosen category, in order, read its file in `assessment/` and go item by item: 1. State the item's title and its "why it matters". 2. Ask for **importance**: 1 Low, 2 Medium, 3 Critical, or N/A (record the reason). N/A means the practice does not apply; if so, mark N/A and move to the next item. Mark an item skipped only when it is outside the selected scope/profile. 3. Interview using the item's "Questions to ask". Skip questions already answered implicitly. For importance 1, ask at most one question. 4. Compare answers against "What good looks like" and "Red flags", then **propose a current-state rating** — 0 Absent, 1 Ad-hoc, 2 Defined, 3 Managed, 4 Optimizing — with a one-sentence rationale. Ask the person to confirm or correct. Until confirmed, mark the rating unconfirmed and do not calculate its gap or score contribution. 5. At the category's "Other" item, ask whether anything important was missed. If there is one general practice, rate the standard "Other" item. If there are multiple distinct practices, mark the standard "Other" item Skipped, record each in a separate custom row with a stable report-local ID (`custom-01`, `custom-02`, ...), and never reuse an ID for a different practice. If reasonable follow-up does not establish a rating, mark it **unknown**; if the team chooses to return later, mark it **deferred**. Neither means state 0 or N/A. Keep any known field and evidence, but do not calculate a score contribution unless both importance and state are confirmed. Reuse evidence across items when it genuinely answers more than one question; do not repeat the same interview question. Explain which part of the evidence applies to each item. A single underlying problem may be linked to multiple item IDs, but combine it into one action when one fix addresses it. After each category, give a two-sentence summary of what you heard before moving on. When an interview must pause, save a copy of `templates/checkpoint.md` with the current spec version, profile identifier/version and exact selected scope. Record each item's importance and state separately with its answer status, preserving confirmed values, notes, and optional safe evidence references. Set the next unanswered item ID in the assessment's normal order. Do not turn unknown or deferred into a rating, and do not include secrets, private personnel records, or unnecessary identifying details. The checkpoint can be stored alongside the report and should follow the same audience and sharing expectations. ## Phase 3 — Report Fill in `templates/report.md` exactly: - Calculate gap priority = importance × (4 − state) only for rows with confirmed importance and state. Calculate category score = Σ(importance × state) / Σ(importance × 4) using confirmed rows only. - For each category, report confirmed applicable items / applicable items in scope. Applicable items include unknown, deferred, and unconfirmed answers; exclude N/A and skipped items. Mark a category provisional if any applicable item is not confirmed. If none is confirmed, show "no score (provisional)". All-N/A categories are "not assessed"; categories excluded at setup are "skipped". - Show max 10 confirmed rows in Top gaps, sorted by raw gap priority descending, ties broken by importance. An action plan can sequence work differently for urgency or dependencies, but preserve the raw gaps and explain the reason. - Keep custom rows out of standard category scores and coverage. Report their confirmed gaps in a separate custom-practices table and calculate a supplemental custom score from confirmed custom rows only; show coverage and provisional status using the same rules as categories. Compare supplemental scores only when custom ID/title sets and weights match; otherwise report the set change and compare shared IDs individually. - Record the system boundary, environment, selected profile/categories/items, assessment date, and evidence date in the report. Evidence references are optional; do not include secrets or private personnel records. - Treat aggregate scores as directly comparable only when both reports are complete and spec version, scope, selected items, and importance weights match. Provisional scores are not directly comparable; compare shared confirmed item states and disclose coverage. If weights change, disclose that and compare confirmed item states separately. If scope or item selection changes, mark aggregate scores not directly comparable. - Write 3–5 recommendations tied to the top gaps: what to do first, why, what "better" looks like in 3–6 months. - Combine related gaps into one recommendation when the same action addresses them, and list every related item ID. - Keep the evidence needed to support ratings in Detailed results. Avoid unnecessary identifying details, and never include secrets or private personnel records. - Before sharing the report, give participants the planned report or relevant summary to review for factual errors and identifying or sensitive details. Incorporate corrections and remove unnecessary identifying details; record any unresolved disagreement neutrally. Do not treat review as changing a rating without evidence. - Record spec version 0.3.0, the date, and participant names or role labels as agreed in the header. Deliver the completed report as a single Markdown document. --- # 1. Product & Vision Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 1.1 Product Overview **Why it matters:** If the team can't articulate the product, its users, and the problem it solves in plain language, every downstream decision — architecture, prioritization, hiring — is guesswork dressed up as strategy. **What good looks like:** Any engineer on the team can explain in a couple of minutes who the product serves, what pain it removes, and why that matters, without reaching for a slide deck. **Questions to ask:** - If you stopped a random engineer in the hallway, could they describe the product and its core users in two sentences? - Who is explicitly *not* the target user, and why was that boundary drawn? - What problem does this solve that the user couldn't solve another way before? - When did the product overview last change, and did the team notice? **Red flags:** the description only exists in a founder's head or a pitch deck; engineers describe the product in purely technical terms with no mention of the user; "it does everything for everyone." ### 1.2 Product Vision / Mission **Why it matters:** Without a shared long-term direction, teams optimize locally — every sprint looks reasonable in isolation but the product drifts without accumulating toward anything. **What good looks like:** A concise, durable statement of where the product is headed exists, is written down, and is referenced (not just recited) when weighing competing priorities. **Questions to ask:** - Where is the vision written down, and when was it last revisited? - Can you give an example of a decision the vision helped settle in the last quarter? - If two people on the team described the vision independently, would they agree? - Has the vision changed recently — and if so, does everyone know? **Red flags:** vision statement is generic boilerplate that could apply to any company; it hasn't been mentioned in a planning meeting in over a year; leadership and engineering describe the direction differently. ### 1.3 Project Goals **Why it matters:** Goals translate vision into something a team can actually plan against and measure; without them, "we're moving fast" substitutes for "we're moving somewhere." **What good looks like:** Short- and mid-term goals are explicit, tied to measurable outcomes, and revisited on a predictable cadence rather than only when something goes wrong. **Questions to ask:** - What are this quarter's goals, and how do they connect to a business or user outcome? - How do you know when a goal has been achieved — what's the measurable signal? - What was the last goal that was missed, and what happened as a result? - How often do stated goals change mid-cycle, and why? **Red flags:** goals are activity-based ("ship feature X") rather than outcome-based; goals exist only as a Jira epic nobody reopens; no one can name this quarter's top goal without checking a document. ### 1.4 Functional and Non-Functional Requirements **Why it matters:** Functional requirements describe what the product does; non-functional ones (security, scalability, reliability) determine whether it survives contact with real usage. Skipping either invites rework or outages later. **What good looks like:** Requirements are captured somewhere durable, distinguish must-have from nice-to-have, and explicitly address non-functional concerns rather than leaving them implicit. **Questions to ask:** - Where do non-functional requirements (performance, security, availability) get written down, if anywhere? - For the last major feature, how were "must have" and "nice to have" distinguished? - What happens when a requirement conflicts with a deadline — who decides what gets cut? - Can you point to a recent incident caused by an unstated non-functional requirement? **Red flags:** requirements live only in a ticket title; non-functional requirements are never discussed until an incident forces the conversation; "we'll figure out scale when we get there" as a standing policy. ### 1.5 Product Roadmap **Why it matters:** A roadmap turns goals into a sequence the team and stakeholders can plan around; without one, priorities feel arbitrary and dependencies get discovered too late. **What good looks like:** A roadmap exists, is visible to the team, names dependencies and rough timing, and is updated often enough to stay credible rather than becoming decorative. **Questions to ask:** - Where does the roadmap live, and who can see it? - When was it last updated, and does it reflect what's actually being worked on right now? - What's an example of a dependency the roadmap surfaced before it became a blocker? - How far out does the roadmap realistically hold — weeks, quarters, longer? **Red flags:** the roadmap is a static slide from a quarterly business review; engineers learn about upcoming priorities from stand-up rather than the roadmap; dates are treated as commitments despite being guesses. ### 1.6 User Research & Feedback Loops **Why it matters:** Product decisions made without user input are bets; regular, structured feedback loops turn those bets into informed choices and catch misdirection early. **What good looks like:** There's a consistent mechanism for gathering user input (interviews, support signals, usage data, beta programs) and evidence that it actually changes what gets built. **Questions to ask:** - What's the most recent product decision that changed because of user feedback? - How do insights from support tickets or sales calls make it back to the product team? - Who talks to users directly, and how often? - If a feature flopped, how would the team find out — and how would they know why? **Red flags:** "we know what users want" asserted without a mechanism behind it; feedback is collected but has no visible path into planning; user research happened once, long ago, and hasn't been repeated. ### 1.7 Product Metrics & Analytics **Why it matters:** Metrics are how a team tells the difference between shipping and succeeding; without them, launches are declared wins by default rather than by evidence. **What good looks like:** A small set of meaningful metrics (adoption, engagement, quality) is tracked, visible to the team, and actually consulted when deciding what to build next. **Questions to ask:** - What are the two or three metrics that most define product success here? - Who looks at the dashboard, and how often? - Can you describe a time a metric moved unexpectedly and what the team did about it? - How do you distinguish a vanity metric from one that drives a decision? **Red flags:** metrics are tracked but nobody can recall the current numbers; dashboards exist but are never opened outside of a quarterly review; success is measured only by "did we ship it," not by impact. ### 1.8 Compliance & Legal Requirements **Why it matters:** Compliance obligations (GDPR, accessibility, industry-specific regulation) carry legal and financial risk if ignored, and retrofitting them after the fact is far more expensive than designing for them upfront. **What good looks like:** Applicable obligations are identified explicitly, someone is accountable for tracking them, and they inform product decisions rather than being discovered during an audit or a customer's security questionnaire. How compliance is operated day-to-day is assessed in [6.10](06-security-compliance.md#610-compliance--data-retention-policies). **Questions to ask:** - Which specific regulations or standards apply to this product, and who determined that list? - Who owns compliance accountability — is there a named person or is it "everyone's job, so no one's"? - What was the last compliance gap discovered, and how was it found — audit, incident, or customer question? - How do new features get checked against compliance obligations before they ship? **Red flags:** compliance is treated as a one-time checkbox rather than an ongoing obligation; no one can name which regulations apply; obligations are only discovered when a customer or regulator asks. ### 1.9 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. ### 1.10 User Experience & Accessibility **Why it matters:** A product can meet its functional goals and still exclude people or make important tasks difficult. Understanding usability and accessibility needs early reduces barriers for users and costly redesign later. **What good looks like:** The team understands the needs of its target users, evaluates important workflows with representative users or equivalent evidence, and checks that people with disabilities can complete them using relevant assistive technologies. Findings inform product decisions and are revisited as the product changes. **Questions to ask:** - How does the team learn whether users can complete the product's most important tasks? - Which users, including people with disabilities, have been represented in that evidence, and whose needs may be missing? - How are keyboard access, screen-reader support, and other relevant accessibility needs evaluated for the product? - What usability or accessibility issue most recently changed a product decision, and how was the fix checked? - Which accessibility standards or legal requirements apply, and how is that obligation tracked? Product obligations are assessed in [1.8](01-product-vision.md#18-compliance--legal-requirements); this item focuses on the user experience and product behavior. **Red flags:** product decisions rely only on internal assumptions; important workflows have not been checked with users or representative evidence; accessibility is treated as a final checklist rather than part of design and development; known barriers have no owner or plan. --- # 2. Processes & Collaboration Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 2.1 Onboarding Process **Why it matters:** How a new hire spends their first weeks predicts how long it takes them to become productive and whether they form an accurate mental model of the codebase — or a folklore one passed down in hallway conversations. **What good looks like:** New team members follow a documented path that gets them to a first meaningful commit within days, with a clear point of contact and materials that are actually kept current. **Questions to ask:** - What did the last new hire do on their first day, and who decided that? - How long did it take the most recent hire to ship their first real change? - Is there a written onboarding checklist or guide, and when was it last used successfully? - What did the last new hire get wrong or confused about that the docs should have covered? **Red flags:** onboarding is "shadow someone for a week and figure it out"; the onboarding doc is a year old and references tools that no longer exist; new hires' first questions go unanswered for days. ### 2.2 Roles and Responsibilities **Why it matters:** When ownership of a domain is fuzzy, decisions stall waiting for someone to claim them, or get made twice by people unaware of each other's work. **What good looks like:** Everyone can name who owns product, engineering, QA, and other key domains, and those owners are the ones actually consulted when decisions in their area come up. **Questions to ask:** - Who owns this codebase, this feature, this decision — can you name them without checking a wiki? - What happens when a decision falls between two roles — who resolves it? - Has anyone left recently, and did their responsibilities have a clear successor? - Can you point to a recent case where unclear ownership caused a delay or a duplicated effort? **Red flags:** "it's kind of everyone's job"; ownership is only documented in an org chart nobody references day to day; the same decision gets re-litigated because no one remembers who made it the first time. ### 2.3 Methodologies and Frameworks **Why it matters:** A team's stated methodology only matters if it's actually practiced; a mismatch between the label on the wall and the work on the ground creates friction and false expectations for anyone new. **What good looks like:** The team can describe the process it actually follows — whether that's Scrum, Kanban, dual-track, or something bespoke — and that description matches what an observer would see in a normal week. **Questions to ask:** - What methodology does the team say it follows, and does a week of observation match that description? - What parts of the "official" process get skipped in practice, and why? - Who decided on this methodology, and has it been revisited since? - What would change if the team switched frameworks tomorrow — anything, or just vocabulary? **Red flags:** ceremonies happen because the calendar says to, not because they produce a decision; the process was copied from a book or a previous company without adaptation; the team can't explain why they do it this way. ### 2.4 Communication **Why it matters:** Information that doesn't reach the people who need it might as well not exist; poor communication cadence and channel hygiene quietly recreates silos even on a small team. **What good looks like:** There's a predictable rhythm and a small number of well-understood channels for different kinds of communication, and important information reliably reaches the people who need to act on it. **Questions to ask:** - If something important happened yesterday, how would you find out — and how long would it take? - How many different channels (Slack, email, tickets, meetings) does someone need to check to stay informed? - What was the last time an important update got missed because of where it was posted? - How do updates reach people who were out or on a different team? **Red flags:** critical decisions get made in a DM that nobody else can see; "check the thread" as a standard response; announcements duplicated across five channels with no single source of truth. ### 2.5 Task Management **Why it matters:** Without a shared, trustworthy view of what's in flight and what's done, planning becomes guesswork and work quietly falls through the cracks. **What good looks like:** Tickets have a consistent format and a clear definition of ready and done, the board reflects reality without heavy manual upkeep, and anyone can tell what's actually being worked on right now. **Questions to ask:** - What does "done" mean for a ticket here — is it written down or tribal knowledge? - Can you trust the board right now, or does it need a cleanup pass before it's accurate? - How does work that isn't a ticket yet (a hallway request, an urgent bug) enter the system? - What's the oldest open ticket, and does anyone know its actual status? **Red flags:** the board is updated only right before a status meeting; "definition of done" varies by person; work happens outside the tracking system entirely and gets reconciled after the fact, if at all. ### 2.6 Prioritization and Decision Making **Why it matters:** Every team has more good ideas than capacity; how trade-offs get decided — and who gets a say — determines whether the team builds the right things or just the loudest requests. **What good looks like:** There's a known process for weighing competing priorities, the people with relevant context are actually involved, and the reasoning behind a call is visible enough to be revisited later. **Questions to ask:** - Who decided what the team is working on this week, and what informed that choice? - Can you point to a recent trade-off decision and explain why it went the way it did? - What happens when an urgent request conflicts with planned work — is there a process, or does it depend on who shouts loudest? - How does the team distinguish between someone's opinion and an informed decision? **Red flags:** priorities shift based on who last talked to a stakeholder; decisions have no visible rationale, only an outcome; the most senior voice in the room wins regardless of the argument. ### 2.7 Project Estimation **Why it matters:** Estimates drive commitments to stakeholders, staffing, and sequencing; when they're systematically wrong and nobody checks, planning becomes theater and trust erodes with every missed date. **What good looks like:** Sizing is produced with a repeatable method, estimates are compared against actuals afterward, and the team's calibration visibly improves — or at least the gap is acknowledged and worked around. **Questions to ask:** - How was the last estimate produced — gut feel, a formal technique, historical data? - Does anyone compare estimates to actuals afterward, and what did the last comparison show? - What happens when a deadline was committed before the estimate existed? - How does uncertainty get communicated — as a range, a confidence level, or a single number treated as fact? **Red flags:** estimates are demanded before requirements are understood; a single number is quoted upward and treated as a promise; nobody ever revisits whether estimates were close. ### 2.8 Code Reviews **Why it matters:** Code review is often the only point where a second engineer engages deeply with a change before it ships; when it's a rubber stamp, the team loses its main defense against design mistakes and knowledge silos. **What good looks like:** Reviews happen promptly, reviewers engage with design and correctness rather than just style, and the process catches real problems often enough that people take it seriously. This item assesses the review interaction and feedback; ownership and reviewer assignment are assessed in 4.13. **Questions to ask:** - How long does a typical pull request wait for its first review comment? - What's the last piece of substantive feedback a review caught before merge — not a typo, an actual design or correctness issue? - Is there a required number of approvals, and is it ever bypassed — by whom, and how often? - How do reviewers handle disagreement with the author — is there a resolution process, or does it default to whoever's more senior? **Red flags:** approvals given without evidence the diff was read; reviews consistently take days, so people route around them; large PRs get a single "LGTM" with no comments. ### 2.9 Retrospectives and Feedback **Why it matters:** Teams that don't pause to reflect repeat the same mistakes; retrospectives are the mechanism for turning lived experience into process change, and their absence shows up as recurring, never-fixed friction. **What good looks like:** Retrospectives happen on a predictable cadence, produce specific action items with owners, and those action items are checked on later rather than forgotten the moment the meeting ends. **Questions to ask:** - What action item came out of the last retro, and what's its status today? - How many retros in a row have raised the same unresolved issue? - Does feedback flow both ways — do individual contributors get to raise process problems, not just report on tickets? - What would have to happen for a retro action item to actually get prioritized against feature work? **Red flags:** retros happen but produce no written action items; the same complaint resurfaces every retro with no visible attempt to fix it; the meeting is treated as a formality to get through, not a working session. ### 2.10 Ground Rules **Why it matters:** Unstated norms around meetings, communication, and behavior default to whatever the most dominant personalities model, which can quietly exclude quieter voices or create friction nobody names directly. **What good looks like:** Basic norms — meeting etiquette, response-time expectations, how disagreement is handled — are written down somewhere, referenced when they're violated, and revisited as the team changes. **Questions to ask:** - Are there written team norms, and can someone point to where they live? - What happens when someone consistently violates a norm — is it addressed, or quietly tolerated? - How were these norms decided — by the whole team, or handed down? - When did the ground rules last get updated, and what prompted the change? **Red flags:** norms exist only as unwritten expectations that new members have to guess at; violations are tolerated from senior people but not from others; the rules haven't been revisited since the team's headcount doubled. ### 2.11 Decision Records (ADR) **Why it matters:** Without a record of why a significant decision was made, the reasoning leaves with the people who were in the room, and future engineers either repeat the debate from scratch or violate a constraint they don't know exists. **What good looks like:** Significant architectural and process decisions are captured in a lightweight, consistent format, are easy to find, and are referenced when a related decision comes up later. **Questions to ask:** - Where do architectural decisions get recorded, and how many exist? - Pick a major technical choice made in the last year — is the reasoning written down anywhere? - When was the last time someone consulted an old ADR before making a related decision? - What decisions should have an ADR but don't? **Red flags:** "we don't really do ADRs, people just remember"; the ADR log exists but hasn't been touched in over a year despite significant changes happening; records exist but are never referenced, so decisions get silently re-litigated. ### 2.12 Cross-Team Collaboration **Why it matters:** Most real work crosses team boundaries — engineering needs design, QA, DevOps, or another engineering team — and the quality of that handoff determines whether work flows or stalls at every interface. **What good looks like:** Interfaces between teams are clear, dependencies are surfaced early, and there's a known way to resolve conflicts or blockers that doesn't require escalating to management every time. **Questions to ask:** - What's the last piece of work that depended on another team, and how smoothly did that handoff go? - How far in advance do cross-team dependencies typically get identified — before or after they become blockers? - When two teams disagree about an interface or a timeline, how does that get resolved? - Is there a standing forum or contact point for coordinating with other teams, or does it happen ad hoc? **Red flags:** dependencies are discovered the week they're due; cross-team requests routinely sit unanswered; every disagreement between teams escalates to a manager instead of being resolved peer to peer. ### 2.13 Stakeholder Management **Why it matters:** Stakeholders who feel uninformed or unheard tend to escalate, micromanage, or lose trust in the team's judgment — all of which cost more time than proactively keeping them in the loop. **What good looks like:** Key stakeholders are identified explicitly, there's a regular cadence for keeping them updated, and their input is gathered before decisions are finalized rather than after. **Questions to ask:** - Who are the key stakeholders for this product, and can the team name them without hesitation? - How and when do stakeholders find out about scope changes or delays — before or after the fact? - What's the last time a stakeholder was surprised by something the team already knew? - How is stakeholder feedback gathered, and where does it go once collected? **Red flags:** stakeholders learn about slipped deadlines in a status meeting instead of proactively; "stakeholder management" means damage control after a surprise, not a standing practice; no one can list the stakeholders for a given initiative. ### 2.14 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # 3. Architecture & Systems Design Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 3.1 System Documentation **Why it matters:** A system that only lives in the heads of its original authors becomes unmaintainable the moment they're unavailable; documentation is what lets someone new reason about the system without archaeology. **What good looks like:** Architecture diagrams, runbooks, and onboarding docs exist, are findable in one obvious place, and are updated as part of making a change rather than as an afterthought months later. **Questions to ask:** - Where's the current architecture diagram, and does it match what's actually deployed? - When was a system doc last updated alongside a code change, versus discovered stale during an incident? - Could a new engineer trace how a request flows through the system using only the docs? - What's the last time outdated documentation sent someone down the wrong path? **Red flags:** the only diagram is a whiteboard photo from two years ago; docs describe a service that was decommissioned; "just ask So-and-so" is the actual onboarding path for understanding the system. ### 3.2 Tech Stack **Why it matters:** Every language, framework, and platform choice carries a long-term maintenance and hiring cost; a stack chosen for the wrong reasons — or never revisited — quietly taxes every future change. **What good looks like:** The team can explain why each major piece of the stack was chosen, those choices are still defensible given current needs, and the stack is small enough that no one is maintaining expertise in five ways of doing the same thing. **Questions to ask:** - Why was each major technology in the stack chosen, and by whom? - Has anything in the stack been added or replaced in the last year, and what drove that? - Are there multiple tools doing the same job because of historical accident rather than deliberate choice? - If you were starting today with what you now know, what would you choose differently? **Red flags:** "it's what the founding engineer knew" as the only rationale still offered; the stack keeps growing but nothing is ever retired; nobody can name a technology that was deliberately rejected and why. ### 3.3 Architecture Patterns **Why it matters:** The chosen architectural style — monolith, microservices, event-driven, layered — shapes how easily the system can change; a pattern applied inconsistently or adopted by trend rather than fit creates friction everywhere it's violated. **What good looks like:** The team can name the architectural pattern in use, explain why it fits the problem and team size, and point to the pattern actually being followed in the code rather than just described in a diagram. **Questions to ask:** - What architectural pattern does the team say the system follows, and does a walk through the codebase confirm it? - Why was this pattern chosen over the alternatives at the time? - Where does the codebase visibly violate the stated pattern, and is that tracked as debt or just accepted? - Has the pattern been revisited as the system or team has grown? **Red flags:** the system is called "microservices" but every service shares a database; the pattern was copied from a conference talk without evaluating fit; boundaries exist on a diagram but not in the actual code. ### 3.4 Loose Coupling / High Cohesion **Why it matters:** Tightly coupled modules turn small changes into system-wide events; when responsibilities are scattered instead of cohesive, understanding or safely changing any one piece requires understanding all of them. **What good looks like:** Modules have clear, narrow interfaces, a change inside one rarely forces changes in unrelated ones, and each module's responsibility can be described in a single sentence. **Questions to ask:** - What's the last change that "should" have touched one module but ended up rippling through several? - Can you name a module's responsibility in one sentence, or does explaining it require several caveats? - How are module boundaries enforced — convention, code review, or something structural like package boundaries? - What's the most tangled part of the system, and does everyone agree on which part that is? **Red flags:** a one-line change routinely requires touching a dozen files across unrelated areas; shared mutable state or global objects are the main way modules communicate; nobody can draw the module boundaries without arguing about where they actually are. ### 3.5 Scalability & Performance **Why it matters:** Systems that aren't built or tested against real load expectations tend to work fine in demos and fail exactly when success — a traffic spike, a big customer — makes failure most costly. **What good looks like:** Load expectations are explicit, the system has been tested against them (not just assumed to hold), and there's a known plan for what breaks first as load grows and what to do about it. **Questions to ask:** - What load is the system actually designed to handle, and where is that number written down? - When was the last load or performance test, and what did it find? - What's the first thing that breaks as traffic doubles — is that known, or a guess? - Can you point to a real incident caused by scale, and what changed afterward? **Red flags:** "it's fine, we've never had a problem" as the entire performance strategy; no load testing has ever been run; performance work only happens reactively, during or after an incident. ### 3.6 Resilience & Fault Tolerance **Why it matters:** Dependencies fail — networks drop, third-party APIs time out, instances crash — and a system that assumes everything downstream always works will eventually take a partial failure and turn it into a total outage. **What good looks like:** Failure modes are anticipated, isolated so they don't cascade, and the system degrades gracefully — with retries, timeouts, and circuit breakers used deliberately rather than as an afterthought bolted on after an incident. **Questions to ask:** - What happens right now if the system's most critical dependency goes down for five minutes? - Are there timeouts and retries on external calls, and were they set deliberately or left at library defaults? - What's the last outage caused by a single point of failure, and has that class of failure been addressed since? - How does the service handle initialization, readiness, and shutdown—for example, draining in-flight work—and how does the team verify those transitions complete safely? - Has failure injection or chaos testing ever been run, or is resilience purely theoretical? **Red flags:** a single dependency failing takes down unrelated functionality; retries with no backoff turn a blip into a self-inflicted overload; nobody knows what the actual blast radius of a given failure would be. ### 3.7 Data Architecture **Why it matters:** Data models and ownership decisions are among the hardest things to change after the fact; unclear ownership or inconsistent guarantees produce corruption, duplicated sources of truth, and migrations everyone dreads. **What good looks like:** Each piece of data has one clear owner, schemas evolve through a deliberate migration process, and consistency guarantees are understood and matched to what each use case actually needs. **Questions to ask:** - For any given piece of data, who or what system owns it, and is that ownership documented? - What's the process for a schema migration — is it tested, reversible, and does it have a rollback plan? - Where does the system rely on eventual consistency, and does everyone touching that data know it? - What's the last data integrity issue, and what allowed it to happen? **Red flags:** the same piece of data is written by multiple services with no clear source of truth; migrations are run manually against production with no rollback plan; nobody can say with confidence whether a given read is strongly or eventually consistent. ### 3.8 APIs & Integrations **Why it matters:** APIs are contracts other teams and systems depend on; breaking one silently — or having no versioning strategy at all — turns an internal change into someone else's outage. **What good looks like:** External and internal contracts are documented, versioned deliberately, and changes are tested against real consumers before they ship, with a clear deprecation path when something has to change. **Questions to ask:** - Is there a versioning strategy for APIs, and has it ever actually been exercised for a breaking change? - How would the team find out if a change broke a consumer — proactively, or when that consumer complains? - Are integration contracts documented somewhere a consumer could find without asking a person? - What's the last integration that broke in production, and why wasn't it caught earlier? **Red flags:** breaking changes ship without notice to consumers; no integration tests exist against real or realistic dependencies; API documentation is stale or doesn't exist, so consumers reverse-engineer behavior from the code. ### 3.9 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # 4. Code & Quality Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 4.1 Codebase Relevance **Why it matters:** Code that no longer reflects current requirements or domain understanding forces every change to fight the existing structure instead of building on it. **What good looks like:** The codebase's structure and domain models track the business as it exists today, and stale code or abandoned approaches are removed rather than left to confuse the next reader. **Questions to ask:** - Does the code's structure still match how the team talks about the domain, or has the business moved on without it? - What's the last feature that was hard to build because the existing code assumed an old version of the business? - How much of the codebase is dead or vestigial, and does anyone know which parts? - When requirements change significantly, does the code get restructured or does a new layer get bolted on top? **Red flags:** entire modules nobody can explain the purpose of; "legacy" code that's actually still load-bearing but treated as untouchable; the domain model in code contradicts how the business actually operates now. ### 4.2 Patterns **Why it matters:** Consistent use of architectural and design patterns lets engineers transfer intuition from one part of the codebase to another; inconsistency means every module has to be learned from scratch. **What good looks like:** A small set of patterns is used deliberately and consistently for recurring problems, the team can name them, and deviations are exceptions with a reason rather than the norm. **Questions to ask:** - What patterns does the team say it uses, and does a walk through a few modules confirm it? - When a new problem looks like one already solved elsewhere in the codebase, does it get solved the same way? - How many different ways does the codebase solve the same kind of problem — e.g., data fetching, validation, error propagation? - Who decides when a new pattern is warranted versus reusing an existing one? **Red flags:** the same problem is solved a different way in every module; patterns were copied from a tutorial without adaptation to this codebase; no one can name the patterns in use without looking them up. ### 4.3 Code Style **Why it matters:** Inconsistent formatting and style turn every code review into a debate about tabs and semicolons instead of substance, and make diffs noisier than the actual change. **What good looks like:** A style guide exists, is enforced automatically by tooling rather than by reviewer memory, and the whole codebase reads as if one disciplined person wrote it. **Questions to ask:** - Is formatting enforced by a tool, or does it depend on the reviewer catching it? - Can you point to the style guide, and does the codebase actually match it? - How much review time gets spent on style comments instead of logic or design? - What happens when a new contributor's editor uses different defaults — does CI catch it or does it slip through? **Red flags:** style arguments recur in every PR; formatting is "whatever your editor does"; different files clearly reflect different eras or authors with no unifying convention. ### 4.4 Engineering Principles **Why it matters:** Principles like SOLID, KISS, and DRY exist to keep change cheap; applied as slogans without judgment they produce as much harm as ignoring them — over-abstraction is as costly as duplication. **What good looks like:** The team applies these principles with judgment, can explain a specific tradeoff they made, and neither duplicates logic carelessly nor abstracts prematurely to satisfy a rule. **Questions to ask:** - Can you point to a place where the team deliberately chose duplication over a premature abstraction, or vice versa? - What's the most over-engineered part of the codebase, and how did it get that way? - How is adherence to these principles discussed in code review — as a checklist or as a judgment call? - What's a rule the team used to follow rigidly that they've since relaxed, and why? **Red flags:** abstractions with a single implementation "in case we need it later"; the same business rule duplicated in five places with no plan to unify it; principles cited as absolute rules rather than tradeoffs. ### 4.5 Error Handling **Why it matters:** How a system handles the unexpected — a failed call, a bad input, a timeout — determines whether a small problem stays small or cascades into an incident nobody can diagnose. **What good looks like:** Errors are handled deliberately at the right layer, logged with enough context to diagnose without reproducing, and surfaced to the right audience — user, operator, or nobody — rather than swallowed or dumped as a stack trace. **Questions to ask:** - When something fails, is that visible anywhere, or does it just disappear silently? - Can you find an example of an error caught and logged with enough context to actually debug it later? - What's the team's convention for when to retry, fail fast, or degrade gracefully? - What's the last incident that was hard to diagnose because the error handling didn't capture what actually happened? **Red flags:** empty catch blocks; errors logged with no context beyond "something went wrong"; the same failure produces a different, inconsistent response depending on which code path hit it. ### 4.6 Technical Debt **Why it matters:** Debt taken on knowingly to move fast is a legitimate tradeoff; debt that's invisible or unmanaged compounds until it silently caps how fast the team can ship. **What good looks like:** Debt is tracked somewhere visible, prioritized against feature work with real tradeoffs made explicit, and paid down deliberately rather than only when it causes an outage. **Questions to ask:** - Where is technical debt tracked, and when was it last reviewed as a group? - Can you name the three biggest pieces of debt right now and what each is costing the team? - Has debt ever been prioritized over a feature, or does feature work always win by default? - How does the team decide whether known bugs are fixed before or alongside new feature work, and what justifies deferring them? - What's the last piece of debt that caused an incident before anyone acted on it? **Red flags:** debt lives only in tribal memory or scattered TODO comments; debt is never paid down until it causes a production incident; every retro mentions the same unaddressed debt as last time. ### 4.7 Package Management **Why it matters:** Dependencies are code the team didn't write but is still responsible for; unmanaged versions, unpinned ranges, and unclear ownership of what's installed create both stability and security exposure. **What good looks like:** Dependency versions are pinned or deliberately ranged, lockfiles are committed and respected, and someone can explain why each major dependency is there and what would happen if it went unmaintained. **Questions to ask:** - Are dependency versions pinned, and is the lockfile actually checked into version control and honored? - Who decides when to add a new dependency, and what's the bar for adding one versus writing it in-house? - Can you name a dependency that's now unmaintained or deprecated, and is there a plan for it? - What happened the last time a dependency upgrade broke something — was it caught before or after release? **Red flags:** no lockfile, or a lockfile that's routinely out of sync with what's actually installed; dependencies added on a whim with no review; a dependency the team knows is abandoned but has no plan to replace. ### 4.8 Unit Tests **Why it matters:** Unit tests give fast feedback on logic and edge cases in individual components; without them, small regressions are harder to find and refactoring stalls. **What good looks like:** Unit tests exercise meaningful behavior and edge cases, finish quickly, and fail reliably when that behavior regresses. Coverage is tracked but not worshipped. Release-level regression confidence is assessed in 5.5; pipeline enforcement is assessed in 5.13. **Questions to ask:** - Can you run the unit test suite locally with one command, and how long does it take? - Do unit tests assert business behavior and edge cases, or are they mostly coupled to implementation details? - When a unit test fails, do people investigate it or re-run it? How are flaky tests handled? - What was the last logic bug a unit test should have caught but did not? **Red flags:** unit tests are too slow or flaky to provide useful feedback; tests assert implementation details but miss important behavior; failures are routinely re-run without investigation. ### 4.9 Integration & E2E Testing **Why it matters:** Unit tests verify pieces in isolation, but most real failures happen at the seams — between services, with the database, through the UI — where only integration and end-to-end tests can catch them. **What good looks like:** Key user journeys and cross-service interactions are covered by tests that run against realistic environments, run often enough to catch regressions quickly, and are stable enough that failures are trusted signal. **Questions to ask:** - What critical user journeys are actually covered by integration or E2E tests, and what's still untested? - How close to production do these tests' environment and data look? - How long do these tests take to run, and does that delay affect whether people run them? - What's the last production bug that only an integration or E2E test could have caught? **Red flags:** integration tests run against mocks so thoroughly they no longer test integration; E2E suite is so slow or flaky it's routinely skipped; critical user journeys have no test coverage at all. ### 4.10 Scaffolding / Project Layout **Why it matters:** A confusing or inconsistent repository structure slows down every new contributor and every routine task, long after the people who set it up have moved on. **What good looks like:** The project layout is predictable, documented, and supported by scripts that make common tasks — setup, running locally, adding a new module — a single command rather than tribal knowledge. **Questions to ask:** - Could a new engineer find where a given piece of functionality lives without asking someone? - Is there a documented convention for where new code should go, and is it actually followed? - How much tribal knowledge is required to set up a local dev environment from scratch? - What's the last time someone put code in the "wrong" place because the right place wasn't obvious? **Red flags:** project structure contradicts its own documentation; setup requires a person to walk you through undocumented steps; similar functionality is scattered across the repo with no consistent home. ### 4.11 Documentation & Domain Language **Why it matters:** Code that uses the same words the business uses is self-documenting; a mismatch between code vocabulary and domain vocabulary means every conversation requires mental translation and invites misunderstanding. **What good looks like:** Class, function, and variable names mirror the language the business actually uses, key concepts are documented where the code lives, and a domain expert reading the code (or its docs) would recognize the concepts. **Questions to ask:** - Do the names in the code match the words used in planning meetings and by the business, or is there a translation layer in everyone's head? - Where does domain knowledge live — in the code and its docs, or only in a few people's heads? - Can you find an example of a term that means one thing to the business and another thing in the code? - When domain understanding changes, does the code's vocabulary get updated, or does it drift further from reality? **Red flags:** engineers and product routinely have to "translate" between what they call something and what the code calls it; core domain concepts have no documentation anywhere; the same concept has several different names across the codebase. ### 4.12 Static Analysis / Linting **Why it matters:** Static analysis catches whole classes of bugs and inconsistencies before a human ever has to look at the code, freeing review time for things a machine can't judge. **What good looks like:** Linting and static analysis run automatically on every change, block merges on real violations, and the ruleset is tuned deliberately rather than left at defaults or silenced wholesale. **Questions to ask:** - What static analysis or linting runs today, and is it enforced in CI or only advisory? - How many warnings or violations are currently suppressed, and does anyone know why? - Has static analysis ever caught a bug before it reached production — can you name one? - Who owns the linting configuration, and when was it last reviewed? **Red flags:** linter warnings routinely ignored or suppressed with blanket disables; static analysis exists but isn't wired into CI; the ruleset hasn't been touched since the project started and no longer fits how the team writes code. ### 4.13 Code Ownership & Review Process Quality **Why it matters:** Clear ownership makes someone accountable for a piece of code's health and helps route changes to people with the right context. Review speed and the substance of feedback are assessed in 2.8. **What good looks like:** Every part of the codebase has a clear owner or owning team, and changes are routed to an owner or qualified reviewer. Ownership includes responsibility for maintenance, not just approval rights. **Questions to ask:** - For a given file or service, could you name its owner or owning team and how a change gets routed to them? - What happens when the owner is unavailable or a change crosses ownership boundaries? - Is there a part of the codebase nobody wants to own or touch? - Who is accountable for the health and maintenance of code their team owns? **Red flags:** large areas have no clear owner; ownership records are stale; changes routinely bypass the owning team without an agreed reason; nobody accepts responsibility for maintaining inherited code. ### 4.14 Dependency Security & Updates **Why it matters:** Vulnerable or outdated dependencies are one of the most common ways systems get compromised, and the risk is invisible until it's exploited or flagged. **What good looks like:** Dependencies are scanned for known vulnerabilities on a regular cadence, updates — especially security patches — are applied promptly, and there's a clear process for what happens when a critical vulnerability is found. **Questions to ask:** - Is there automated scanning for vulnerable dependencies, and who actually looks at the results? - What's the typical time between a critical vulnerability being disclosed and it being patched here? - How far behind are the major dependencies from their latest stable versions, and is that a deliberate choice? - What's the last security patch that was delayed, and what caused the delay? **Red flags:** vulnerability scan results exist but nobody acts on them; dependencies are years behind current versions with no plan to catch up; a known critical vulnerability has sat unpatched for months. ### 4.15 Copyright & Licenses **Why it matters:** Every dependency and piece of borrowed code carries a license with real legal obligations; getting this wrong can create liability that surfaces only during an acquisition, audit, or lawsuit. **What good looks like:** Dependency licenses are tracked and checked automatically, incompatible or high-risk licenses are flagged before they're merged in, and the project's own licensing is clear and intentional. **Questions to ask:** - Is there an automated check for dependency license compatibility, or does it rely on someone noticing? - Can anyone explain what license the project itself is under and why that was chosen? - Has a dependency with a restrictive or incompatible license ever made it into the codebase? - Who would know what to do if legal asked for a full accounting of third-party licenses in use? **Red flags:** no one has ever checked dependency licenses; copy-pasted code of unknown origin exists in the codebase; the project's own license file is missing, wrong, or was never deliberately chosen. ### 4.16 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # 5. Engineering Practices & Delivery Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 5.1 Version Control System **Why it matters:** The branching strategy and history shape how safely and quickly changes move from a developer's machine to production; a confused strategy creates merge pain and hides what's actually deployed where. **What good looks like:** A documented, consistently followed branching strategy maps cleanly to the release process, commit history is legible, and tags or version markers make it possible to know exactly what code is running anywhere. **Questions to ask:** - Can you describe the branching strategy from memory, and does the actual repo history match that description? - How do you know, right now, exactly what code is deployed to production versus what's in the default branch? - What happens when two people need to work on unrelated changes at the same time — does the workflow support that cleanly? - What's the last time a merge went wrong, and what about the branching model made it possible? **Red flags:** long-lived branches that drift for months before merging; tags that don't correspond to what's actually deployed; commit history full of "fix," "wip," and "asdf" with no way to reconstruct why a change was made. ### 5.2 Project Installation **Why it matters:** How easily a new machine can be brought to a working local setup determines onboarding speed and how often "works on my machine" derails a debugging session. **What good looks like:** A documented, scripted setup gets a new contributor from a clean checkout to a running local environment in one or two commands, with dependencies and prerequisites pinned and explicit. **Questions to ask:** - How long did it take the last new hire to get a fully working local environment, and how much of that required someone's help? - Is setup a single documented command, or a checklist of steps that has to be followed exactly in order? - What happens if you follow the setup instructions on a completely clean machine today — do they still work? - How are OS or environment differences (Mac vs. Linux vs. containers) handled? **Red flags:** setup docs that are known to be stale; "ask Dave" is the actual onboarding process; setup only works because of undocumented local state on existing developers' machines. ### 5.3 Project Launch **Why it matters:** Standing up a new environment or deploying the product for the first time is a rare enough event that undocumented tribal knowledge disappears exactly when it's needed most. **What good looks like:** A written, current playbook covers what it takes to launch the project into a new environment end-to-end, and someone outside the usual owner could follow it without live coaching. **Questions to ask:** - If the person who usually handles launches was unavailable, could someone else follow existing docs to stand up a new environment? - When was this playbook last actually used, and did it work as written or need live fixes? - What manual, undocumented steps still happen during a launch that live only in someone's head? - What's the biggest surprise the last time this process ran? **Red flags:** the playbook exists but hasn't been executed by anyone except its author; steps that only work because one person remembers an undocumented gotcha; no playbook at all — launches happen "by feel." ### 5.4 Project Build **Why it matters:** The build is the boundary between source code and a deployable artifact; if it's slow, inconsistent, or opaque, every downstream step inherits that uncertainty. **What good looks like:** Builds are reproducible from a clean checkout, fast enough not to bottleneck delivery, versioned and stored in a way that any past artifact can be retrieved, and their output is a known, verifiable unit. **Questions to ask:** - Can you rebuild last month's release artifact byte-for-byte from source, or has that become impossible? - How long does a full build take, and has that time been trending up? - Where are built artifacts stored, and how far back can you retrieve one? - How is a built artifact's provenance recorded and verified before deployment—for example, with a signature or build attestation—and how can it be tied to reviewed source? - What's the last time a build succeeded locally but failed — or behaved differently — in CI or production? **Red flags:** builds that only work on one person's machine; no artifact retention beyond the current release; build steps that silently depend on external network state or unpinned tool versions. ### 5.5 Project Testing **Why it matters:** Release-level regression testing checks that critical user paths still work across the system as it will run. Unit and integration test design is assessed in 4.8 and 4.9; this item focuses on the confidence the release candidate provides. **What good looks like:** The team knows which critical user paths and system interactions its release-level regression checks cover, how representative their environment and data are, and what gaps remain. The results inform a deliberate release-confidence decision. Automated gates and deployment enforcement are assessed in 5.13. **Questions to ask:** - Which critical user journeys and system interactions are covered by release-level regression checks, and which important paths remain untested? - How closely do the test environment and data represent the release environment and data? - How does the team decide whether regression results provide enough confidence in a release candidate? - What was the last production regression that unit or integration tests did not catch, and what did it reveal about the release-level checks? **Red flags:** critical user paths have no release-level regression evidence; the suite is stale or unlike production; known test gaps are not considered in release decisions. ### 5.6 Automation **Why it matters:** Manual, repetitive operational work is slow, inconsistent between people, and a constant source of small mistakes that automation would eliminate entirely. **What good looks like:** Routine operational tasks — dependency bumps, changelogs, environment provisioning, repetitive checks — are automated with scripts or bots, and the team actively looks for the next manual task worth automating. **Questions to ask:** - What's a task the team does by hand every week that could plausibly be scripted, and why hasn't it been? - What automation exists today (bots, scheduled jobs, GitHub Actions), and who maintains it when it breaks? - How much of the release or deployment process still requires a human to run a manual command at the right time? - What's the last piece of automation that broke silently and nobody noticed for a while? **Red flags:** automation scripts nobody currently on the team understands or maintains; the same manual, error-prone task performed by hand every single release; bots or automation that fail silently with no alerting. ### 5.7 Performance and Efficiency **Why it matters:** Without deliberate attention, systems tend toward accumulating waste — slow paths, redundant work, unnecessary resource use — that compounds as the system grows. **What good looks like:** Performance and efficiency work is driven by measurement, not guesswork, targets the paths that actually matter to users or cost, and is revisited periodically rather than only after something breaks. **Questions to ask:** - What's the last performance or efficiency improvement made, and how was the target identified — measurement or hunch? - Is there a known slow path or expensive operation everyone's aware of but nobody has prioritized fixing? - How is performance regression caught — is it measured continuously or only noticed when a user complains? - What tradeoffs were made the last time something was optimized — did it cost readability, flexibility, or reliability? **Red flags:** optimization work driven entirely by anecdote rather than profiling or metrics; a known-slow critical path nobody has scheduled time to address; premature optimization that added complexity without measurable benefit. ### 5.8 Environment Parity **Why it matters:** The gap between staging (or any pre-production environment) and production is where "it worked in testing" bugs come from; the closer the parity, the more the team can trust results from earlier environments. **What good looks like:** Environments are clearly defined with a real purpose each, configuration differences between them are minimal and explicit, and promotion between environments follows a consistent, known path. **Questions to ask:** - What environments exist today, and can everyone on the team name the purpose of each without hesitation? - How different is staging's configuration, data, and scale from production — and does that difference ever cause surprises? - How is non-secret configuration defined, versioned, reviewed, and supplied to each environment without mixing it with secrets? - What's the last bug that only showed up in production because an earlier environment didn't catch it? - Is there an environment that's supposed to mirror production but has quietly drifted out of sync? **Red flags:** staging configuration diverges so much from production that passing there means little; an environment that exists but no one remembers why or trusts; promotion between environments is ad hoc rather than a repeatable process. ### 5.9 Release Management Process **Why it matters:** How a release gets approved, scheduled, and communicated determines whether shipping is a routine, low-stress event or a high-anxiety scramble every time. **What good looks like:** Releases follow a known cadence or clear trigger, have defined approval gates appropriate to their risk, and produce release notes or communication that lets stakeholders know what changed. **Questions to ask:** - Who has to approve a release before it ships, and does that approval reflect real risk assessment or is it a formality? - How often does the team release, and is that cadence a deliberate choice or just "whenever"? - Where do release notes come from — are they written deliberately or reconstructed after the fact from commit messages? - What's the last release that went out without anyone outside engineering knowing it happened? **Red flags:** releases happen with no consistent process — different every time depending on who's driving; approval gates that exist on paper but are routinely skipped under deadline pressure; no communication to stakeholders about what shipped or when. ### 5.10 Recovery Plan **Why it matters:** Every deployment pipeline eventually ships something broken; what separates a minor blip from a prolonged outage is whether rollback and recovery are rehearsed rather than improvised under pressure. **What good looks like:** Rollback is a fast, well-understood, low-risk operation, hotfix paths exist for urgent patches without going through the full release cycle, and worst-case recovery procedures have actually been tested, not just documented. **Questions to ask:** - How long does it take to roll back a bad release right now, and when was that last actually exercised — not just discussed? - Is there a fast path for an urgent hotfix, or does every fix have to go through the full normal release process? - What's the worst-case recovery scenario (data loss, full outage), and has a plan for it ever been tested end-to-end? - Who is authorized to trigger a rollback, and are they available outside business hours? **Red flags:** rollback has never actually been tested, only assumed to work; recovery procedures exist only as a document nobody has rehearsed; a single person is the only one who knows how to execute recovery. ### 5.11 Observability **Why it matters:** Without logs, traces, and dashboards that reflect what the system is actually doing, diagnosing a production problem becomes guesswork under pressure instead of a directed investigation. **What good looks like:** Logging and tracing provide enough context to reconstruct what happened during an incident without reproducing it, dashboards reflect the metrics that actually matter to the business and system health, and instrumentation is added as a normal part of building a feature. **Questions to ask:** - When the last incident happened, could the team reconstruct the sequence of events from logs and traces alone, or did it require guesswork? - Are dashboards something the team actually looks at day to day, or do they exist and go unopened? - How is a new feature instrumented — is adding logging/tracing part of the definition of done, or an afterthought? - Can you trace a single request across every service it touches, or does visibility stop at a service boundary? **Red flags:** logs exist but lack the context needed to actually diagnose anything; dashboards that were built once and never revisited as the system changed; tracing that stops at the first service boundary with no cross-service visibility. ### 5.12 Monitoring & Alerting Quality **Why it matters:** Monitoring and alerting are what turn observability data into action — the difference between a well-tuned alerting system and a noisy one is the difference between fast incident response and alert fatigue that causes real problems to be ignored. **What good looks like:** Alerts map to defined SLOs/SLIs, firing on conditions that actually require human action, response workflows are clear about who gets paged and what they do next, and alert noise is actively tracked and reduced. **Questions to ask:** - What percentage of alerts in a typical week require real action versus getting dismissed or ignored? - Are there defined SLOs/SLIs, and do alerts actually map to breaches of them? - When an alert fires at 3am, does the responder know exactly what to do, or are they figuring it out live? - What's the last real incident that didn't generate an alert until a user reported it? **Red flags:** alert fatigue so bad that pages get muted or ignored by default; no defined SLOs, so "alert-worthy" is whatever someone decided in the moment; the same noisy alert firing for months with nobody fixing its root cause. ### 5.13 CI/CD **Why it matters:** The CI/CD pipeline is the automated gate between a commit and a deployed change; how much it actually enforces — versus how much it merely reports — determines how much the team can trust "green" to mean "safe to ship." **What good looks like:** Every change passes through automated quality gates (tests, linting, security checks) before merge, deployment is automated and repeatable rather than a manual sequence of commands, and pipeline failures block progress rather than being routinely overridden. Test-suite quality is assessed in 4.8 and 4.9; release regression confidence is assessed in 5.5. **Questions to ask:** - What quality gates actually block a merge or deploy, versus which ones just report status that people ignore? - How much of deployment is a single automated action versus a human running commands in a particular order? - How often is a pipeline failure overridden or bypassed to ship anyway, and by whom? - What's the time from merge to production right now, and where does most of that time go? **Red flags:** pipeline failures routinely overridden under deadline pressure; deployment still requires a human to run manual steps in the right order; quality gates exist but are advisory rather than blocking. ### 5.14 Infrastructure as Code (IaC) **Why it matters:** Infrastructure that exists only as manual console clicks is undocumented, unreviewable, and impossible to reliably reproduce; treating infrastructure as versioned code brings it the same rigor as application code. **What good looks like:** Infrastructure is defined declaratively in version-controlled code, changes go through the same review process as application code, and environments can be reliably recreated from that code alone. **Questions to ask:** - Could the production environment be recreated from code alone, or does it depend on manual configuration nobody wrote down? - Do infrastructure changes go through code review the same way application changes do? - What's the last infrastructure change made directly in a cloud console rather than through code? - Is there drift between what the IaC defines and what's actually running — has anyone checked recently? **Red flags:** critical infrastructure configured by hand and never captured in code; infrastructure changes made directly in a console with no review trail; known drift between declared infrastructure and actual running state. ### 5.15 Cost Efficiency / Cloud Optimization (FinOps) **Why it matters:** Cloud and infrastructure spend that goes unexamined tends to grow faster than usage justifies, and by the time it becomes a visible problem it's often deeply entangled with the architecture. **What good looks like:** Spend is tracked, attributed to teams or services, and reviewed on a regular cadence with clear ownership for acting on waste — not just reported, but actually optimized. **Questions to ask:** - Who owns cloud spend, and when was it last reviewed with an eye toward cutting waste rather than just reported? - Can spend be attributed to specific services or teams, or is it one undifferentiated bill? - What's the last piece of obviously wasted spend (idle resources, oversized instances) that was found and eliminated? - Are cost implications considered when architecture or infrastructure decisions are made, or only discovered after the bill arrives? **Red flags:** nobody can explain what's driving a significant fraction of the cloud bill; cost review happens rarely or never, only reported after the fact with no one acting on it; known idle or oversized resources left running because addressing them isn't anyone's job. ### 5.16 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # 6. Security & Compliance Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 6.1 Security Requirements **Why it matters:** Security bolted on after design is always more expensive and less complete than security considered from the start; without an explicit threat model, teams defend against whatever they happened to think of rather than what actually threatens the system. **What good looks like:** A lightweight threat model exists for the system, is revisited when the architecture changes meaningfully, and translates into concrete controls that are tracked rather than left as good intentions. **Questions to ask:** - Has anyone written down what or who this system needs to be protected from, and when was that last revisited? - Can you point to a specific control that exists because of an identified threat, not just as a generic best practice? - When a new feature touches sensitive functionality, does threat modeling happen before or after it ships? - Who owns security requirements — is it a named responsibility or does it fall through the cracks between product and engineering? - How are security priorities and responsibilities communicated to the teams building and operating the system? - Which security measures or outcomes does the team track, and how do those measures influence decisions? - What secure-coding guidance or training is available to engineers, and how is it reinforced in day-to-day work? **Red flags:** no threat model exists in any form, written or verbal; security is "whatever the framework does by default"; security requirements are discovered retroactively, after an incident or audit. ### 6.2 Sensitive Data Protection **Why it matters:** Data that's exposed, over-collected, or under-protected turns a routine breach into a reportable, reputation-damaging incident, and the cost of getting this wrong is borne long after the original engineering decision is forgotten. **What good looks like:** Sensitive data is classified, encrypted at rest and in transit, masked or tokenized where full values aren't needed, and collected only when there's a real, current use for it. **Questions to ask:** - Can you list the categories of sensitive data this system stores, and who classified them as sensitive? - Where does encryption stop — is anything sensitive stored or logged in plaintext, including in backups or logs? - Who has access to raw sensitive data, and is that access narrower than "anyone with database credentials"? - What's collected today that nobody actually uses — has data minimization ever been revisited? **Red flags:** sensitive fields show up unmasked in application logs or error trackers; "we encrypt the database" is the entire answer with no detail on what, how, or key ownership; data is retained indefinitely because deleting it was never someone's job. ### 6.3 Input Validation **Why it matters:** Every external entry point — API, form, file upload, webhook, message queue — is a place an attacker or a malformed client can inject something the system wasn't built to handle; validation at the boundary is what keeps bad input from becoming a bad outcome deeper in the system. **What good looks like:** All external inputs are validated and sanitized at the boundary using a consistent approach, validation failures are rejected with a clear response rather than silently coerced, and the same rules are enforced regardless of which entry point is used. **Questions to ask:** - Can you walk through what happens when malformed or unexpected input hits an API endpoint — where exactly is it caught? - Is validation applied consistently across all entry points, or does it depend on which developer built that endpoint? - Has an injection-class vulnerability (SQL, command, template, XSS) ever been found here, and how was it caught? - What happens to input that fails validation — is it logged, alerted on, or does it just disappear? **Red flags:** validation exists on some endpoints but not others, with no consistent standard; client-side validation is trusted as sufficient on its own; user-controlled input is concatenated directly into queries, commands, or templates. ### 6.4 Authentication / Authorization **Why it matters:** Authentication answers "who is this," authorization answers "what can they do" — get either wrong and every other control is moot, because the wrong party is standing in front of the system with the wrong level of access. **What good looks like:** Identity is verified through a modern, well-vetted mechanism (not homegrown), authorization follows least privilege with roles or policies that are reviewed periodically, and privilege escalation requires a deliberate, auditable action. **Questions to ask:** - Is authentication built on a standard, vetted mechanism, or does the system roll its own session or token handling? - Can you trace how a permission check actually happens for a sensitive action — is it enforced centrally or scattered across the codebase? - When was access and role assignment last reviewed for staleness — do former employees or unused service accounts still have access? - What's the most privileged role in the system, who holds it, and how is that access justified? **Red flags:** authorization checks are duplicated ad hoc in each handler instead of centralized; roles were assigned once and never revisited; a homegrown password or session scheme exists instead of a standard library or provider. ### 6.5 Credentials **Why it matters:** Passwords, API keys, and service tokens that are hardcoded, shared, or never rotated turn a single leaked value into standing, often invisible access — and the leak is frequently discovered only after it's been exploited. **What good looks like:** Credentials for people and services live in a secrets manager, are never committed to source control, are scoped to the minimum needed, and are rotated on a schedule or automatically rather than only after a suspected compromise. **Questions to ask:** - Where do secrets actually live today — a vault, environment variables, or somewhere they could end up in version control? - When did any given credential — a database password, an API key — last rotate, and was that on a schedule or reactive? - If a specific credential leaked right now, how would the team find out, and how long would it take to revoke it? - Are credentials scoped narrowly per service, or does one shared key unlock more than it needs to? **Red flags:** secrets found in git history, config files, or Slack messages; a shared credential used across multiple services or environments with no way to revoke one without breaking the others; rotation has never happened for a long-lived credential. ### 6.6 Key Management **Why it matters:** Cryptographic keys are what make encryption meaningful — a well-encrypted system with poorly managed keys is only as secure as wherever those keys sit unprotected, and losing or leaking a key can be as damaging as never encrypting at all. **What good looks like:** Encryption and signing keys are generated, stored, and rotated through a dedicated key management system (not alongside application secrets), access to keys is scoped and audited, and there's a defined process for rotation and for responding to a suspected key compromise. **Questions to ask:** - Where do cryptographic keys live, and is that separate from where application credentials and secrets are stored? - Who can access or use a signing or encryption key directly, and is every use of it logged? - What's the key rotation policy, and has it actually been exercised — not just written down? - If a key were suspected of being compromised today, is there a rehearsed process for revoking and replacing it without an outage? **Red flags:** encryption keys stored alongside the data they protect, or in the same secrets store with no distinction from application credentials; no audit trail of key usage or access; a key has been in use since the system launched with no rotation ever performed. ### 6.7 Vulnerability Management & Dependency Scanning **Why it matters:** Exploitable weaknesses show up across containers, base images, running infrastructure, and cloud configuration — not just application dependencies — and without an org-wide program for finding and triaging them, coverage gaps go unnoticed until an attacker finds them first. **What good looks like:** Automated scanning covers every surface — container images, infrastructure, cloud configuration, running services — on a regular cadence, findings roll up to a single triage process with clear ownership and severity-based SLAs, and escalation for critical findings is documented and governed at the organization level rather than left to whichever team owns the affected system. Day-to-day dependency patching hygiene is assessed in [4.14](04-code-quality.md#414-dependency-security--updates); this item covers the organization-wide scanning and triage program. **Questions to ask:** - What surfaces are covered by the scanning program — containers, infrastructure, cloud config, running services — and which ones, if any, aren't? - Who owns the org-wide triage process, and does every team's findings feed into it, or do some teams run their own silently? - What's the governed SLA by severity, and can you show a critical infrastructure finding that met — or missed — it? - If a new scanning gap opened up (a new service, a new cloud account), how would the program notice? **Red flags:** scanning exists for code dependencies but nothing covers containers, infrastructure, or cloud configuration; each team runs its own ad hoc scanning with no org-wide rollup or shared SLA; a critical infrastructure or container finding sat unactioned because no one owned triage outside the application layer. ### 6.8 Penetration Testing / Audits **Why it matters:** Automated scanning catches known vulnerability patterns, but only an adversarial human test — internal or external — reliably surfaces the logic flaws, chained exploits, and business-context weaknesses that tools miss. **What good looks like:** Penetration tests or security audits happen on a defined cadence or before major changes, findings are tracked to remediation with real deadlines, and the team treats results as input to prioritization rather than a compliance artifact to file away. **Questions to ask:** - When was the last penetration test or security audit, who performed it, and what was the highest-severity finding? - Of the findings from the last test, how many were actually remediated, and how many are still open? - Is testing triggered by a schedule, a compliance requirement, or only after something already went wrong? - Does anyone outside the security or compliance function ever see the results, or does the report go straight to a drawer? **Red flags:** the most recent test is more than a year old, or one has never been performed; findings from the last test are still open with no remediation plan; testing exists solely to produce a document for a customer or auditor, with no intent to act on it. ### 6.9 Incident Response Process **Why it matters:** Every system eventually has a security incident; whether that incident is contained in hours or festers for weeks depends entirely on whether detection, response, and communication were planned before the pressure was on, not improvised during it. **What good looks like:** Detection mechanisms are in place, a written incident response plan defines roles and escalation paths, the plan has actually been exercised (not just written), and every real incident produces a blameless post-mortem with tracked follow-through. **Questions to ask:** - Is there a written incident response plan, and when did the team last run a drill or tabletop exercise against it? - Walk through the last real security incident — how was it detected, and how long from detection to containment? - Who has authority to declare an incident and make containment decisions at 2am, and do they know that role is theirs? - What did the last post-mortem produce, and were those action items actually completed? **Red flags:** no written incident response plan exists, or one exists but has never been rehearsed; the last incident was discovered by a customer or the public before the team noticed internally; post-mortems happen but their action items are rarely followed up on. ### 6.10 Compliance & Data Retention Policies **Why it matters:** Regulatory and contractual obligations carry real legal and financial consequences, and retention policies that are undefined or unenforced mean the organization is either holding data it has no right to keep or unable to produce data it's obligated to retain. **What good looks like:** Applicable compliance obligations are operationalized into concrete, enforced controls, data retention and deletion schedules are defined per data category and actually executed (not just documented), and evidence of compliance can be produced on demand rather than assembled under pressure. Which obligations apply to the product is assessed in [1.8](01-product-vision.md#18-compliance--legal-requirements); this item covers how retention and compliance are operated. **Questions to ask:** - For a given data category, what's the defined retention period, and can you show it's actually enforced rather than just written down? - If an auditor asked for evidence of a specific control right now, how long would it take to produce it? - Who owns day-to-day compliance operations, and is that distinct from whoever decided which obligations apply? - Has a data deletion or retention request (e.g., a user's right-to-erasure request) ever been tested end to end? **Red flags:** retention policy exists as a document but no automated or manual process enforces it; data past its retention date is still sitting in production or backups; compliance evidence has to be reconstructed from scratch every time it's requested rather than being readily available. ### 6.11 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # 7. Culture & External Factors Part of the [Software Project Maturity Assessment](../ASSESSMENT.md) — spec version 0.3.0. ### 7.1 Working Conditions **Why it matters:** Tooling friction, noisy environments, and poor ergonomics are a constant tax on attention; engineers who fight their environment every day have less left for the actual problem. **What good looks like:** Engineers have the hardware, software licenses, and workspace (physical or remote) they need without a fight, and requests to fix friction are resolved in days, not quarters. **Questions to ask:** - What's the most recent piece of hardware or tooling you requested, and how long did it take to get it? - Is there anything you work around every day because getting it fixed properly isn't worth the effort of asking? - How would you describe your build/test feedback loop on your actual machine — is local iteration fast enough to stay in flow? - If you needed a second monitor, more RAM, or a paid tool license tomorrow, what's the process? **Red flags:** engineers self-fund tools or hardware because expensing them is too much friction; long-standing environment complaints nobody owns; "just deal with it" is the answer to raised friction. ### 7.2 Remote Work / Hybrid Efficiency **Why it matters:** Distributed and hybrid teams either build deliberate habits for asynchronous work and inclusive meetings, or they quietly become two-tier organizations where whoever is in the room (physical or first-to-type) has more influence and better information. **What good looks like:** Decisions and important context are captured in writing by default, meetings are run so remote participants have equal voice, and cross-timezone work doesn't consistently land on the same people's off-hours. **Questions to ask:** - Can you name a decision that was made in a hallway or in-office conversation and only reached remote teammates late, or not at all? - When a meeting has both remote and in-office participants, does it actually work for the remote side, or are they observers? - What's written down asynchronously versus what only exists as tribal knowledge from a conversation you had to be present for? - Across time zones, whose working hours get inconvenienced by default? **Red flags:** "you had to be there" is a recurring phrase; async updates are theater while the real decisions happen in a side channel or in-person; one timezone consistently absorbs the inconvenient meeting times. ### 7.3 HR & Recruiting Alignment **Why it matters:** Engineering and people operations that don't talk to each other produce mismatched hiring bars, roles that don't match the work, and attrition nobody sees coming until it's an exit interview. **What good looks like:** Engineering has real input into hiring bar and role definitions, people operations understands what's happening on the ground (workload, morale, attrition risk) before it becomes a crisis, and the two functions coordinate rather than operate in silos. **Questions to ask:** - When was the last time engineering leadership and HR/people ops talked about team health, and what came out of it? - Who sets the technical hiring bar — is it engineering, or does HR run the process largely independently? - If someone on the team were flight-risk right now, would people ops know before they resigned? - How closely does the actual job match what was advertised or promised at hiring time? - Are interviews structured around consistent, role-relevant criteria, and do interviewers have guidance to assess candidates consistently and fairly? **Red flags:** engineers learn about org changes affecting them from HR announcements rather than any prior conversation; hiring bar is set unilaterally by whichever function runs the process; exit interviews surface the same complaint repeatedly with no visible change. ### 7.4 Continuous Learning & Growth **Why it matters:** A team that stops learning stagnates technically and loses its best people to teams that don't; growth has to be a structural investment (time, budget, paths) rather than something squeezed into whatever's left of a person's own time. **What good looks like:** There's real budget and protected time for learning, growth paths exist and are understood (not just an org chart with one ladder), and knowledge-sharing happens as a habit, not an occasional event. **Questions to ask:** - When did you last use a training budget, attend a conference, or take a course on work time — and was it easy to get approved? - Do you know what it would take to get promoted or move to a different track, or is that opaque? - How can team members access coaching or mentoring, and how are those relationships helping them develop skills or pursue career goals? - Is there a recurring guild, brown-bag, or knowledge-sharing session, and do people actually show up? - What's something you learned recently that you had to pursue entirely on your own time and dime? **Red flags:** training budget exists on paper but is never actually spent or approved; growth paths are undocumented and depend on informal advocacy; knowledge-sharing sessions were tried once and quietly died from lack of attendance. ### 7.5 Team Health & Culture **Why it matters:** Morale, psychological safety, and wellbeing aren't soft add-ons — they're leading indicators; teams that feel unsafe to speak up or are quietly burning out will show the damage in quality and attrition long before it shows up in a survey. **What good looks like:** People raise disagreement, mistakes, and bad news without fear of punishment, workload and burnout are actively monitored rather than assumed fine, and DEI is practiced as equitable access to opportunity, mentorship, and fair treatment — not just a stated value with no visible outcome. **Questions to ask:** - When did someone last disagree with a tech lead's or manager's decision in the open, and what happened afterward? - How would the team find out if a teammate was quietly burning out — is anyone watching for it, or does it surface only at resignation? - Can you describe a mistake that was owned openly and discussed without blame, versus one that got swept under the rug? - Do people from different backgrounds get equal access to high-visibility work, mentorship, and fair feedback here? - Is there a way to raise a concern about team culture or conduct that doesn't require going through the person you have the concern about? **Red flags:** disagreement with leadership is rare or happens only privately, never in open forums; burnout is discovered at resignation, not before; DEI exists on paper with no accountability or visible outcomes; concerns can only be raised through the person the concern is about. ### 7.6 Other Anything important to this category that the items above did not cover. Record it here with an importance and state rating like any other item. --- # Report template # Software Project Maturity Assessment Report | | | |---|---| | **Team / Product** | {{TEAM_NAME}} | | **Date** | {{DATE}} | | **Spec version** | 0.3.0 | | **Participants** | {{NAMES_OR_ROLE_LABELS_AS_AGREED}} | | **Intended audience / sharing** | {{AUDIENCE_AND_STORAGE_OR_SHARING_EXPECTATIONS}} | | **System boundary** | {{SYSTEMS_AND_SERVICES_IN_SCOPE}} | | **Environment(s)** | {{ENVIRONMENTS_IN_SCOPE}} | | **Profile / categories / items** | {{SELECTED_SCOPE}} | | **Evidence date or range** | {{EVIDENCE_DATE_OR_RANGE}} | ## Scoring key Importance: 1 Low, 2 Medium, 3 Critical, N/A not applicable (reason recorded). Current state: 0 Absent, 1 Ad-hoc, 2 Defined, 3 Managed, 4 Optimizing. Importance sets the team's priorities; the common score reference is state 4 for every item. Gap priority = importance × (4 − state), max 12. Category score = Σ(importance × state) / Σ(importance × 4), using confirmed ratings only. An item contributes only when both its importance and state are confirmed. Answer status is **Confirmed**, **Unknown**, **Deferred**, **Unconfirmed**, **N/A**, or **Skipped**. Unknown, deferred, and unconfirmed items are not zero or N/A and do not contribute to scores. Show confirmed applicable items / applicable items in scope; the latter includes unknown, deferred, and unconfirmed items but excludes N/A and skipped items. Mark a category **provisional** if any applicable item is not confirmed. If no item is confirmed, show "no score (provisional)". If all items are N/A, show "not assessed"; categories excluded at setup are "skipped". Top gaps include confirmed ratings only and are sorted by raw gap priority descending, ties broken by importance. An action plan may sequence work differently for urgency or dependencies; preserve the raw gap values and explain the reason. Aggregate scores are directly comparable only when both reports are complete and spec version, system boundary, environment, selected items, and importance weights match. Provisional scores are not directly comparable; compare shared confirmed item states and disclose coverage. If weights change, disclose this and compare confirmed item states separately. If scope or item selection changes, mark aggregate scores not directly comparable. Evidence references are optional; do not include secrets or private personnel records. Summarize sensitive evidence at the team level where possible. Omit unnecessary names and private details. Before sharing, give participants a chance to review the report for factual errors and identifying or sensitive details; record unresolved disagreements neutrally. ## Summary | Category | Score / status | Coverage | Top gap | |---|---|---|---| | 1. Product & Vision | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 2. Processes & Collaboration | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 3. Architecture & Systems Design | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 4. Code & Quality | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 5. Engineering Practices & Delivery | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 6. Security & Compliance | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | | 7. Culture & External Factors | {{PCT_COMPLETE_OR_PROVISIONAL_OR_NOT_ASSESSED_OR_SKIPPED}} | {{CONFIRMED_APPLICABLE / APPLICABLE}} | {{ITEM_OR_NONE}} | ## Top gaps (improvement roadmap) Up to 10 items, sorted by gap priority descending. | Rank | Item | Importance | State | Gap priority | Note | |---|---|---|---|---|---| | 1 | {{ID_AND_TITLE}} | {{1-3}} | {{0-4}} | {{N}} | {{ONE_LINE}} | ## Custom practices (supplemental) Custom rows use stable report-local IDs such as `custom-01`; do not reuse an ID for a different practice. When custom rows are present for a category, mark its standard “Other” prompt Skipped. Custom rows do not affect standard category scores or coverage. Report their gap priorities here and calculate the supplemental score from confirmed custom rows only. Show coverage and whether the supplemental score is provisional. If no custom rows were identified, write “None identified.” | ID | Category | Practice | Importance | State | Status | Gap priority | Note | |---|---|---|---:|---:|---|---:|---| | {{CUSTOM_ID}} | {{CATEGORY}} | {{PRACTICE}} | {{1-3}} | {{0-4}} | {{STATUS}} | {{N_OR_NOT_SCORED}} | {{NOTE}} | - **Supplemental custom score:** {{PERCENT_OR_NO_SCORE}} ({{CONFIRMED}} / {{APPLICABLE}} confirmed; {{COMPLETE_OR_PROVISIONAL}}) - **Custom comparison limits:** {{MATCHING_SET_OR_CHANGED_IDS_AND_WEIGHTS}} ## Recommendations 3–5 short narrative recommendations, each tied to the gaps above: what to do first, why, and what "better" would look like in 3–6 months. Combine related gaps into one action when a single fix addresses them, and list all related item IDs. 1. {{RECOMMENDATION}} ## Detailed results One table per assessed category; repeat this structure for each. ### {{N}}. {{CATEGORY_NAME}} — {{SCORE_STATUS_AND_COVERAGE}} | Item | Importance | State | Answer status | Gap priority | Notes | |---|---|---|---|---|---| | {{ID_AND_TITLE}} | {{1-3_OR_N/A_OR_UNSET}} | {{0-4_OR_UNSET}} | {{CONFIRMED_UNKNOWN_DEFERRED_UNCONFIRMED_N/A_SKIPPED}} | {{N_OR_NOT_SCORED}} | {{NOTES}} | ## Appendix - **N/A items and reasons:** {{LIST}} - **Unknown, deferred, or unconfirmed items and missing evidence:** {{LIST_OR_NONE}} - **Skipped items or categories and scope reason:** {{LIST_OR_NONE}} - **Free-form notes ("Other" items):** {{LIST}} - **Comparison limits or changes in scope, profile, or importance weights:** {{DETAILS_OR_NONE}} --- # Interview checkpoint template # Assessment interview checkpoint Use this file to resume an interrupted assessment without losing confirmed answers. Store it with the report under the same audience and sharing expectations. Keep notes concise; omit secrets, private personnel records, and unnecessary identifying details. Evidence references are optional and must be safe to share with the intended audience. ## Assessment context | Field | Value | |---|---| | Spec version | {{SPEC_VERSION}} | | Profile name and version | {{PROFILE_AND_VERSION_OR_CUSTOM}} | | Selected categories and exact items | {{SELECTED_SCOPE}} | | System boundary and environment | {{BOUNDARY_AND_ENVIRONMENT}} | | Assessment date | {{DATE}} | | Evidence date or range | {{EVIDENCE_DATE_OR_RANGE}} | | Intended audience / sharing | {{AUDIENCE_AND_STORAGE_OR_SHARING_EXPECTATIONS}} | | Last updated | {{TIMESTAMP_OR_DATE}} | | Next unanswered item | {{ITEM_ID_AND_TITLE_OR_COMPLETE}} | For a custom profile, record the included item IDs explicitly. A profile version identifies the selection definition; it does not replace the assessment spec version. ## Item answers Include every in-scope item reached so far. Record importance and state independently because either may be confirmed while the other remains unresolved. Use `Confirmed`, `Unknown`, `Deferred`, `Unconfirmed`, `N/A`, or `Skipped` for each field's status. A confirmed value must include the participant-confirmed value; an unresolved value stays blank. Record a reason for N/A or Skipped. | Item ID and title | Importance value | Importance status | State value | State status | Notes and rationale | Safe evidence reference (optional) | |---|---|---|---|---|---|---| | {{ID_AND_TITLE}} | {{1-3_OR_N/A_OR_BLANK}} | {{STATUS}} | {{0-4_OR_BLANK}} | {{STATUS}} | {{CONCISE_NOTES_OR_REASON}} | {{SAFE_REFERENCE_OR_NONE}} | ## Resume instructions Verify the spec version, profile, and selected scope with the participant. Carry forward confirmed fields and notes without asking for them again. Continue at **Next unanswered item** in the selected assessment order. Ask again only about fields marked Unknown, Deferred, or Unconfirmed when the participant is ready to revisit them. Do not infer missing answers from the checkpoint or fill gaps with defaults. If the scope or spec changed, explain that before continuing and record the change; do not silently reuse answers for items whose meaning or selection changed. A resumed run should produce the same report data as an uninterrupted run when context and confirmed answers are unchanged. --- # Lite assessment profile # Lite assessment profile **Profile version:** lite-v1 **Spec version:** 0.3.0 The lite profile is a 30–60 minute first pass for discovery or a focused re-check. It selects 15 items across all seven categories to sample product direction, team flow, system design, code quality, delivery, security, and team health. The duration is a planning target, not a measured guarantee; actual time depends on evidence availability and follow-up. Record the actual duration in the report and use issue #10's pilot work to validate the target. ## Selected items Ask the importance and state questions for these items in the order shown. Ask at most one targeted interview question per item unless a short follow-up is needed to establish evidence and propose a rating. | Order | Item | Why this item is in the first pass | |---:|---|---| | 1 | 1.2 Product Vision / Mission | Establishes whether the team has a clear direction. | | 2 | 1.6 User Research & Feedback Loops | Checks whether user evidence informs product decisions. | | 3 | 2.5 Task Management | Samples how work is made visible and tracked. | | 4 | 2.8 Code Reviews | Checks a key collaboration and change-quality practice. | | 5 | 3.6 Resilience & Fault Tolerance | Samples how the system behaves when dependencies fail. | | 6 | 3.8 APIs & Integrations | Checks service boundaries and integration reliability. | | 7 | 4.8 Unit Tests | Samples fast feedback on component behavior. | | 8 | 4.13 Code Ownership & Review Process Quality | Checks whether code has clear owners and reviewer routing. | | 9 | 5.9 Release Management Process | Samples how changes are approved and communicated. | | 10 | 5.10 Recovery Plan | Checks whether recovery has an owner and a rehearsed path. | | 11 | 5.13 CI/CD | Checks delivery gates and deployment repeatability. | | 12 | 6.1 Security Requirements | Samples how project security risks and controls are identified. | | 13 | 6.5 Credentials | Checks whether service and user credentials are protected. | | 14 | 7.1 Working Conditions | Samples whether people have the tools and environment they need. | | 15 | 7.5 Team Health & Culture | Checks whether concerns and workload risks can be raised safely. | ## What this profile leaves out The lite profile does not assess every item in any category. It omits several important areas, including detailed requirements, architecture, integration and end-to-end testing, dependency updates, observability, vulnerability management, retention, and learning practices. A high lite score is not a complete project health result and must not be presented as one. Use the full profile for a comprehensive assessment or when a material risk needs deeper review. At setup, record **Lite profile lite-v1** and the selected item IDs. Mark in-scope but unselected items **Skipped** because of the selected profile; mark the other items in an unassessed category **Skipped** as well. Do not mark them N/A. Calculate category scores from confirmed selected items only and report selected-item coverage. Compare aggregate scores only with reports using the same spec version, lite-v1 selection, system scope, and importance weights.