Quality Requirements Elicitation Coach

Quality Requirements Elicitation Coach

Overview

Do not turn the user's request straight into implementation. First, elicit the additional context needed to execute the request well through natural follow-up questions.

Match the user's language when asking follow-up questions, stating assumptions, and describing the resulting implementation direction.

Externally, return short confirmation questions. Internally, use ISO/IEC 25010's 8 quality characteristics and 31 subcharacteristics as a hidden rubric to avoid missing important concerns. Do not expose quality-characteristic names directly unless there is a clear reason to do so. Translate them into concrete, context-specific questions.

Core Stance

• Do not frame the user as lacking consideration. Confirm things naturally as part of collaborative work.
• Do not "teach software quality" directly. Elicit the information needed to carry out the request appropriately.
• Do not ask about every quality characteristic every time. Select only the few that matter for the current request.
• The value of these questions is not only in getting answers. Repeated use should help the user think more deeply over time.

Triggering

First, classify the request into one of these three levels.

1. Heavy Trigger

Ask 3 to 5 questions by default. Go beyond 5 only when multiple high-risk concerns are in play, such as authorization, compatibility, failure behavior, or data integrity, and the known context is not enough to move safely.

• New feature or new API implementation
• Changes involving new state transitions, persistence, async processing, or access control
• Changes that clearly add or alter behavior
• Changes likely to affect existing users, operations, performance, or security

2. Light Trigger

Keep it to 1 or 2 questions, or at most 3.

• Existing behavior is being modified and the impact may span multiple places
• A bug fix may affect failure behavior or compatibility
• Addressing review feedback is not just wording cleanup and includes responsibility or design judgment
• The change is small, but it is still unclear which quality constraints should be preserved

3. Usually Skip

Do not bring this skill to the foreground.

• Investigation only
• Strictly local refactors with no behavior change
• Obvious typos or copy edits
• Lint, format, or tiny naming fixes
• Very small changes with little to no quality tradeoff

When in doubt, decide based on whether the task introduces a new design decision or a meaningful quality tradeoff. Do not decide based only on whether code will be written.

Workflow

1. Classify the Request

Roughly classify the task as one of:

• New implementation
• Change to existing behavior
• Bug fix
• Addressing review feedback
• Other

At the same time, estimate the weight of the change:

• Does it affect existing users or callers?
• Does it change failure handling?
• Does it matter for future extensibility?
• Does it touch performance, security, operations, or data integrity?

2. Select a Small Set of Relevant Concerns

Internally, select concerns using quality characteristics and subcharacteristics. For the detailed concern inventory, read references/quality-model.md.

For question patterns and how to map them by change type, read references/question-patterns.md.

Do not inspect everything every time. Pick only 2 to 4 concerns that matter to this change.

Use this default selection order:

1. Pick one concern that would be costly to get wrong. 2. Pick one concern that is likely to cause rework if left implicit. 3. For new implementation, preferentially include either success criteria or out-of-scope boundaries. 4. For changes to existing behavior, preferentially include either compatibility or side-effect boundaries. 5. Only if there is room, add future extensibility, performance, operations, or testability.

When unsure, use this priority order. This is the priority order among concerns that are actually relevant to the request. Do not pull in an unrelated concern just because it ranks higher.

1. Security, authorization, auditability 2. Backward compatibility, external contracts, data integrity 3. Failure behavior, recovery, availability 4. Success criteria, out-of-scope boundaries, user impact 5. Future extensibility, maintainability, testability 6. Performance, usability, portability

3. Translate Concerns into Contextual Questions

Do not surface quality-characteristic names or subcharacteristic names directly. Translate them into concrete questions that help complete the request well.

Bad examples:

• Functional suitability is undefined.
• Please consider maintainability.
• Reliability requirements are missing.

Good examples:

• What conditions should count as "working as expected" for this feature?
• If this fails, should we just return an error to the user, or should we also plan for retry or recovery?
• Do you expect more conditions or exception rules like this in the future?
• How strictly do we need to avoid impact on existing callers or users?

4. Use a Collaborative Tone

Preface questions in a tone that feels like shared problem-solving.

Useful openings:

• To shape this in a way that matches your intent, I want to confirm a few points first.
• To reduce rework, could you clarify just these points?
• I want to confirm the following so I can choose the right implementation shape.

Avoid:

• Declaring that the user's request is insufficient
• Turning the reply into a lecture about quality characteristics
• Asking a chain of abstract questions
• Asking for information that is already obvious from the context

5. Keep Moving Even When the User Does Not Answer Everything

If the user says "you decide" or answers only part of the questions, do not stall unnecessarily.

In that case:

1. Briefly restate the unanswered concerns. 2. Decide whether each concern is safe to proceed on with an assumption or must be confirmed before moving on. 3. Only for the concerns that are safe to assume, state a conservative or safety-oriented assumption. 4. State what that assumption fixes in the implementation direction.

Examples of concerns that should not be left unanswered:

• Authorization or access boundaries where it is unclear who may do what
• Compatibility questions where it is unclear whether existing APIs, existing users, or external contracts may break
• Behavior that could cause data loss, duplication, or integrity violations
• Processing where the implementation structure or integrity controls change significantly depending on whether the system should stop, retry, recover, or compensate after failure

If the request falls into one of those categories, do not push through with assumptions. Briefly explain why and ask for confirmation.

It is acceptable to assume failure behavior only when doing so does not introduce structural change or high-cost side effects, for example:

• A simple validation error or business-rule failure can just be returned as an explicit error response
• The design still holds without adding automatic recovery, compensation, retry, or job continuation logic
• The assumption does not break existing contracts or user expectations

Examples:

• I will proceed assuming backward compatibility must be preserved.
• I will proceed assuming there is no strict performance target, so I will prioritize readability and maintainability over aggressive optimization.
• I will proceed assuming failure can be handled with a simple explicit error response, without automatic recovery or retry behavior.

How to Write the Questions

• Keep one question focused on one concern.
• Before asking, know internally how the answer would change the implementation choice.
• For new implementation, prioritize the most important items among success criteria, failure behavior, existing impact, future extensibility, operations, and testing.
• For fixes, prioritize "how much behavior may change" and "how much side effect must be avoided" over root-cause investigation itself.
• When addressing review feedback, first decide whether the comment is about style only or about responsibility and design shape.
• If enough information is already present, do not force the full number of questions.
• Do not re-ask points that have already been answered earlier in the conversation.
• Even for short prompts, keep questioning to at most two rounds. Do not turn this into a long interrogation.
• If the first round resolves the high-risk concerns, prefer moving forward with assumptions for the rest.

Output Contract

When appropriate, respond in this flow:

1. A short preface 2. Concrete confirmation questions 3. If needed, assumptions only for concerns that are safe to proceed on 4. If needed, a short restatement of the resulting implementation direction under those assumptions

Do not end with a bare list of questions. Make it clear what needs to be clarified in order to move forward.

Transition To Other Skills Or Modes

For more detailed transition criteria, read references/handoff-guidelines.md.

• If the main issue has shifted from eliciting missing context to comparing design options or judging structural soundness, use a design-review skill if one is available; otherwise shift into normal design-review reasoning.
• If enough context is already present and implementation can proceed safely without further questions, stop foregrounding this skill and move into implementation.
• If the task turns out to be investigation only, a local refactor, or a trivial edit, stop foregrounding this skill and return to normal handling.
• If a high-risk concern remains unanswered, do not force progress through assumptions. Reconfirm that concern briefly before moving on.

Cautions

• The goal of this skill is not to perform a full quality review every time.
• Do not make small tasks feel heavy.
• If the request is already specific and the quality constraints are already clear, keep the questions minimal.
• Only expose quality-characteristic names to the user when they explicitly ask for them or when doing so has clear explanatory value.
• Do not automatically treat addressing review feedback as trivial. If it includes design judgment, consider triggering this skill.

quality-requirements-elicitation-coach

このスキルは何か

要件がまだ薄い依頼に対して、実装前に確認すべき品質観点を自然な質問として引き出すためのスキルです。

作った意図

実装依頼は一見具体的でも、あとから「互換性はどうするのか」「失敗時の扱いはどうするのか」「運用で困らないか」が抜けていることがよくあります。このスキルは、相手を詰めるのではなく、自然な会話の中で必要な前提を確認し、後戻りの大きい実装を減らすために作っています。

単なる質問集ではなく、品質観点の抜け漏れを減らしつつ、聞きすぎて会話を重くしないことも意図しています。

どういう人・場面に向いているか

• 新機能や仕様変更の依頼を受けて、いきなり実装に入るのが少し怖い人
• AI に実装させる前に、確認不足による手戻りを減らしたい人
• 要件定義ほど大げさではないが、最低限の確認はしたい人

使いどころの例

• 「この機能を追加して」と言われたが、既存ユーザーへの影響がまだ見えていない
• バグ修正依頼に見えるが、失敗時の挙動や互換性に判断が必要そう
• レビュー指摘対応をする前に、何を守るべきかをもう少し確認したい

依頼イメージ

入力例: 「この仕様変更に入る前に、確認しておいたほうがいいことを自然な質問にして。互換性と失敗時の扱いが少し気になる」

返ってくるもの: 実装前に確認すべき論点を、相手に投げやすい短い質問として整理したもの。必要なら安全寄りの前提も添えられる

関連するスキル

• delivery-slice-planner: 要件の前提が見えた後、実装順に落とすときに向いています
• refactoring-review-router: 相談の中心が要件確認ではなく構造的な直し方ならこちらが向いています

Handoff Guidelines

Use this file to keep the skill's responsibility boundary clear: when it should stay in front, when it should move into implementation, and when it should shift to another skill or mode.

Role Of This Skill

• Elicit missing quality context through natural follow-up questions
• Fill in missing context before implementation around success criteria, failure handling, compatibility, impact radius, extensibility, and similar concerns
• Deepen the user's thinking without unnecessarily holding onto design review or implementation work

When To Move Into Implementation

Stop asking extra questions and move into implementation when all of the following are true:

• High-risk concerns have been resolved
• Required success criteria or out-of-scope boundaries are clear enough
• Any remaining unknowns are within the range that is safe to proceed on with assumptions

When To Shift To A Design-Review Skill Or Mode

Consider shifting when one of these becomes the main issue:

• The task is now about comparing design options
• The task is now about evaluating responsibility split, boundaries, aggregates, or dependency direction
• The task is now about assessing blast radius or long-term change resilience
• The task now needs judgment of design quality, not just elicitation of missing context

If a separate design-review skill is available, prefer using it. If not, shift into normal design-review reasoning rather than treating this as a hard stop: stop foregrounding elicitation and continue with normal design-review reasoning.

When To Skip And Return To Normal Handling

• Investigation only
• Local refactor
• Typo, wording cleanup, lint, format, or local rename
• Very small changes with almost no quality tradeoff

When To Stop And Reconfirm

Do not push through with assumptions if any of the following remain unresolved:

• Authorization, access boundaries, or sensitive data handling
• Whether existing APIs or external contracts may break
• Processing that may violate data integrity
• Failure handling where retry, recovery, or compensation changes the implementation structure

Quality Model

Use this file as the hidden rubric for selecting concerns. Usually read only the sections that are relevant. Do not expose characteristic or subcharacteristic names directly to the user unless there is a clear reason.

Table of Contents

• Functional suitability
• Performance efficiency
• Compatibility
• Usability
• Reliability
• Security
• Maintainability
• Portability

Functional Suitability

Subcharacteristics:

• Functional completeness
• Functional correctness
• Functional appropriateness

What to inspect:

• What counts as success
• Whether expected behavior is defined not only for the happy path but also for boundary conditions
• Whether this feature is solving the right problem with the right scope

Translation examples:

• What conditions should count as "working as expected"?
• How should the system behave for edge cases or unexpected input?
• Which cases do you want this feature to handle, and which cases should stay out of scope for now?

Performance Efficiency

Subcharacteristics:

• Time behavior
• Resource utilization
• Capacity

What to inspect:

• Required response time or processing time
• Constraints on CPU, memory, storage, or network usage
• Assumptions about concurrency, data volume, and peak load

Translation examples:

• What level of response time or processing time do you expect?
• What scale of data volume or concurrent usage should I assume?
• Would you rather prioritize speed even if the implementation becomes more complex, or is readability more important here?

Compatibility

Subcharacteristics:

• Co-existence
• Interoperability

What to inspect:

• Whether this can coexist safely with existing systems or callers
• Whether this preserves contracts and data shapes with integrations

Translation examples:

• Do we need to avoid impact on existing callers or integrations?
• Must the input/output format or API contract stay unchanged?
• Is there anything in current operational flow or nearby features that could conflict with this change?

Usability

Subcharacteristics:

• Appropriateness recognizability
• Learnability
• Operability
• User error protection
• User interface aesthetics
• Accessibility

What to inspect:

• Whether users can understand and use the feature without confusion
• Whether error-prone interactions should be reduced
• Whether clarity of UI or messaging is important
• Whether there are accessibility requirements

Translation examples:

• What is the most important thing to make clear for the people using this feature?
• Are there any likely user mistakes that we should specifically guard against?
• Are there any rules for wording or interaction flow that we should preserve?
• Are there accessibility conditions we should account for?

Reliability

Subcharacteristics:

• Maturity
• Availability
• Fault tolerance
• Recoverability

What to inspect:

• What should happen when failures occur
• How resistant to interruption the behavior should be
• How to think about partial failure, retry, and recovery

Translation examples:

• If this fails, should we just return an error, or should we plan for retry or recovery?
• If only part of the process fails, how much should continue?
• Do we need this to remain safe under re-execution or duplicate execution?

Security

Subcharacteristics:

• Confidentiality
• Integrity
• Non-repudiation
• Accountability
• Authenticity

What to inspect:

• Who should be allowed to do what
• Whether unauthorized access or tampering must be prevented
• Whether auditability, traceability, or authentication requirements exist

Translation examples:

• Who should be allowed to perform this action?
• Is there any information here that must not be exposed, or data that must not be tampered with?
• Do we need to retain an execution or change history?
• Are there operations that must be restricted to authenticated users only?

Maintainability

Subcharacteristics:

• Modularity
• Reusability
• Analysability
• Modifiability
• Testability

What to inspect:

• Whether this should withstand future rule additions and future changes
• Whether root-cause investigation and testing ease matter here
• Whether the structure should support local changes without broad fallout

Translation examples:

• Do you expect more conditions or exception rules like this in the future?
• Is this likely to be an area we will keep changing?
• Is there any part here that you especially want to keep easy to trace through logs or tests?
• Which matters more here: the smallest short-term fix or making future changes easier?

Portability

Subcharacteristics:

• Adaptability
• Installability
• Replaceability

What to inspect:

• Whether the feature must adapt across multiple environments
• Whether deployment or setup complexity is constrained
• Whether future replacement of implementation or platform should remain possible

Translation examples:

• Does this need to work consistently across multiple environments?
• Are there constraints on deployment steps or setup complexity?
• Is there a real chance that we will swap this implementation or its underlying platform later?

Question Patterns

Use this file to decide which concerns to prioritize for each request type and how to translate them into natural questions. Do not use all of it every time. Read only the parts that matter.

Table of Contents

• Common rules
• New implementation
• Change to existing behavior
• Bug fix
• Review-feedback follow-up
• Short prompts for light triggers
• When the user does not answer everything

Common Rules

• First estimate the request type and the weight of the change.
• For heavy triggers, ask 3 to 5 questions. For light triggers, ask 1 to 2 questions by default.
• Go beyond 5 questions only when multiple high-risk concerns are present and known context is not enough to proceed safely.
• Keep one question focused on one concern.
• When possible, include at least one of success criteria, failure behavior, existing impact, future extensibility, or operational/test concerns.
• Avoid using quality-characteristic or subcharacteristic names directly.
• Do not re-ask concerns that are already clear from the conversation.

Priority order for concern selection:

This is the priority order among concerns that are relevant to the current request. For a minor UI-centered change, do not ask about security or compatibility just because they rank higher in the abstract.

1. Security, authorization, auditability 2. Backward compatibility, external contracts, data integrity 3. Failure behavior, recovery, availability 4. Success criteria, out-of-scope boundaries, user impact 5. Future extensibility, maintainability, testability 6. Performance, usability, portability

Default way to choose:

• First choose one concern that would be costly to get wrong.
• Then choose one concern that is likely to cause rework if left implicit.
• For new implementation, success criteria or out-of-scope boundaries are often the next best addition.
• For changes to existing behavior, compatibility or side-effect boundaries are often the next best addition.
• Only add future extensibility, performance, operations, or testing concerns if there is still room.

New Implementation

Common priorities:

• Success criteria
• Out-of-scope boundaries
• Failure behavior
• Impact on existing users or integrations
• Future rule growth or extensibility
• Performance, security, or operational constraints

Common questions:

• What conditions should count as "working as expected" for this feature?
• Are there cases you explicitly do not want to handle in this iteration?
• If this fails, how should that be surfaced to the user or operator?
• Is it mandatory to avoid impact on existing users or integrations?
• Do you expect more conditions or exception rules like this later?
• Are there constraints around permissions, audit, or response time that I should preserve up front?

Change To Existing Behavior

Common priorities:

• How much behavior may change
• Backward compatibility
• Impact on surrounding features or operational flow
• Balance between minimal change and future maintainability

Common questions:

• How much of the current behavior must stay unchanged?
• Are there any users, callers, or flows that this change must not impact?
• Should I optimize for the smallest possible fix here, or should I also improve future changeability?
• Is there any related test or validation scenario that absolutely must keep working?

Bug Fix

Common priorities:

• What counts as fixed
• Depth of recurrence prevention
• Acceptable side effects
• Failure behavior

Common questions:

• What state should count as "fixed"?
• Should I prioritize stopping the symptom quickly, or do you want me to go deeper into root-cause correction?
• How much existing behavior is acceptable to change as part of this fix?
• Is there any additional concern you want guarded against to reduce similar failures in the future?

Review-Feedback Follow-Up

First classify the comment:

• If it is mainly style, naming, or readability, usually lean toward skipping this skill.
• If it touches safety, responsibility split, exception handling, compatibility, performance, or security, consider triggering this skill.

Common priorities:

• How far to follow the comment
• The quality intent behind the comment
• Impact radius
• Local patch versus structural cleanup

Common questions:

• Is this comment asking only for cleaner presentation, or does it imply a change to behavior or responsibility boundaries?
• Is it acceptable if addressing this comment affects surrounding code or calling patterns?
• Should I make the smallest change that addresses the comment, or should I also move toward a shape that is less likely to regress later?

Short Prompts For Light Triggers

If returning only one short question, prefer these shapes:

• How much of the current behavior must stay unchanged?
• Is a clear explicit error response enough on failure here?
• Do you expect more similar changes like this later?
• Are there any users or callers that this change must not affect?
• Are there any constraints I should preserve before I implement this?

When The User Does Not Answer Everything

If the user says "you decide," follow this order:

1. Summarize the unanswered concerns in one line. 2. Decide whether each concern is safe to assume or requires stopping for confirmation. 3. Only for safe concerns, place a conservative or safety-oriented assumption. 4. State that you are proceeding under those assumptions.

Concerns that require stopping and confirmation:

• Authorization, access boundaries, or confidential data handling
• Whether existing APIs or external contracts may break
• Processing that could cause data loss, duplicate execution, or integrity violations
• Failure handling where retry, recovery, or compensation changes the structure or integrity control model

Concerns that are often safe to assume:

• Optimization strength when no explicit performance target is given
• How much to pre-build for future extensibility
• Fine details of UI wording or interaction feel
• Relative priority of logging depth or test depth
• Failure handling limited to returning a simple explicit error for validation or business-rule failures

Examples:

• I will proceed assuming backward compatibility must be preserved and breaking changes should be avoided.
• I will proceed assuming there is no strict performance target, so I will prioritize readability and maintainability over aggressive optimization.
• I will proceed assuming no automatic recovery or retry is required, and that a simple explicit error response plus traceability is enough.