@ngocsangairvds/vsaf 4.0.7 → 4.0.9

package/skills/sdlc/bmad-checkpoint-preview/step-02-walkthrough.md

@@ -0,0 +1,89 @@
+# Step 2: Walkthrough
+
+Display: `Orientation → [Walkthrough] → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- Organize by **concern**, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files.
+- The walkthrough activates **design judgment**, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system.
+
+## BUILD THE WALKTHROUGH
+
+### Identify Concerns
+
+**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail):
+
+1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
+2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule.
+3. Read the diff to understand what each stop actually does.
+4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.
+
+**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable):
+
+1. Get the diff against the appropriate baseline (same rules as step 1).
+2. Identify concerns by reading the diff for cohesive design intents:
+   - Functional groupings — what user-facing behavior does each cluster of changes support?
+   - Architectural layers — does the change cross boundaries (API → service → data)?
+   - Design decisions — where did the author choose between alternatives?
+3. For each concern, identify the key code locations as `path:line` stops.
+
+### Order for Comprehension
+
+Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet.
+
+If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it.
+
+### Write Each Concern
+
+For each concern, produce:
+
+1. **Heading** — a short phrase naming the design intent (not a file name, not a module name).
+2. **Why** — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here.
+3. **Stops** — each stop on its own line: `path:line` followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop.
+
+Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway.
+
+## PRESENT
+
+Output the full walkthrough as a single message with this structure:
+
+```
+Orientation → [Walkthrough] → Detail Pass → Testing
+```
+
+Then each concern group using this format:
+
+```
+### {Concern Heading}
+
+{Why — 1–2 sentences}
+
+- `path:line` — {brief framing}
+- `path:line` — {brief framing}
+- ...
+```
+
+End the message with:
+
+```
+---
+
+Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can:
+- "run advanced elicitation on the error handling"
+- "party mode on whether this schema migration is safe"
+- or just ask anything
+
+When you're ready, say **next** and I'll surface the highest-risk spots.
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## NEXT
+
+Default: read fully and follow `./step-03-detail-pass.md`

package/skills/sdlc/bmad-checkpoint-preview/step-03-detail-pass.md

@@ -0,0 +1,106 @@
+# Step 3: Detail Pass
+
+Display: `Orientation → Walkthrough → [Detail Pass] → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- The detail pass surfaces what the human should **think about**, not what the code got wrong. Machine hardening already handled correctness. This activates risk awareness.
+- The LLM detects risk category by pattern. The human judges significance. Do not assign severity scores or numeric rankings — ordering by blast radius (below) is sequencing for readability, not a severity judgment.
+- If no high-risk spots exist, say so explicitly. Do not invent findings.
+
+## IDENTIFY RISK SPOTS
+
+Scan the diff for changes touching risk-sensitive patterns. Look for 2–5 spots where a mistake would have the highest blast radius — not the most complex code, but the code where being wrong costs the most.
+
+Risk categories to detect:
+
+- `[auth]` — authentication, authorization, session, token, permission, access control
+- `[public API]` — new/changed endpoints, exports, public methods, interface contracts
+- `[schema]` — database migrations, schema changes, data model modifications, serialization
+- `[billing]` — payment, pricing, subscription, metering, usage tracking
+- `[infra]` — deployment, CI/CD, environment variables, config files, infrastructure
+- `[security]` — input validation, sanitization, crypto, secrets, CORS, CSP
+- `[config]` — feature flags, environment-dependent behavior, defaults
+- `[other]` — anything risk-sensitive that doesn't fit the above (e.g., concurrency, data privacy, backwards compatibility). Use a descriptive tag.
+
+Sequence spots so the highest blast radius comes first (how much breaks if this is wrong), not by diff order or file order. If more than 5 spots qualify, show the top 5 and note: "N additional spots omitted — ask if you want the full list."
+
+If the change has no spots matching these patterns, state: "No high-risk spots found in this change — the diff speaks for itself." Do not force findings.
+
+## SURFACE MACHINE HARDENING FINDINGS
+
+Check whether the spec has a `## Spec Change Log` section with entries (populated by adversarial review loops).
+
+- **If entries exist:** Read them. Surface findings that are instructive for the human reviewer — not bugs that were already fixed, but decisions the review loop flagged that the human should be aware of. Format: brief summary of what was flagged and what was decided.
+- **If no entries or no spec:** Skip this section entirely. Do not mention it.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → [Detail Pass] → Testing
+```
+
+### Risk Spots
+
+For each spot, one line:
+
+```
+- `path:line` — [tag] reason-phrase
+```
+
+Example:
+
+```
+- `src/auth/middleware.ts:42` — [auth] New token validation bypasses rate limiter
+- `migrations/003_add_index.sql:7` — [schema] Index on high-write table, check lock behavior
+- `api/routes/billing.ts:118` — [billing] Metering calculation changed, verify idempotency
+```
+
+### Machine Hardening (only if findings exist)
+
+```
+### Machine Hardening
+
+- Finding summary — what was flagged, what was decided
+- ...
+```
+
+### Closing menu
+
+End the message with:
+
+```
+---
+
+You've seen the design and the risk landscape. From here:
+- **"dig into [area]"** — I'll deep-dive that specific area with correctness focus
+- **"next"** — I'll suggest how to observe the behavior
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## TARGETED RE-REVIEW
+
+When the human says "dig into [area]" (e.g., "dig into the auth changes", "dig into the schema migration"):
+
+1. If the specified area does not map to any code in the diff, say so: "I don't see [area] in this change — did you mean something else?" Return to the closing menu.
+2. Identify all code locations in the diff relevant to the specified area.
+3. Read each location in full context (not just the diff hunk — read surrounding code).
+4. Shift to **correctness mode**: trace edge cases, check boundary conditions, verify error handling, look for off-by-one errors, race conditions, resource leaks.
+5. Present findings as a compact list — each finding is `path:line` + what you found + why it matters.
+6. If nothing concerning is found, say so: "Looked closely at [area] — nothing concerning. The implementation is solid."
+7. After presenting, show only the closing menu (not the full risk spots list again).
+
+The human can trigger multiple targeted re-reviews. Each time, present new findings and the closing menu only.
+
+## NEXT
+
+Read fully and follow `./step-04-testing.md`

package/skills/sdlc/bmad-checkpoint-preview/step-04-testing.md

@@ -0,0 +1,74 @@
+# Step 4: Testing
+
+Display: `Orientation → Walkthrough → Detail Pass → [Testing]`
+
+## Follow Global Step Rules in SKILL.md
+
+- This is **experiential**, not analytical. The detail pass asked "did you think about X?" — this says "you could see X with your own eyes."
+- Do not prescribe. The human decides whether observing the behavior is worth their time. Frame suggestions as options, not obligations.
+- Do not duplicate CI, test suites, or automated checks. Assume those exist and work. This is about manual observation — the kind of confidence-building no automated test provides.
+- If the change has no user-visible behavior, say so explicitly. Do not invent observations.
+
+## IDENTIFY OBSERVABLE BEHAVIOR
+
+Scan the diff and spec for changes that produce behavior a human could directly observe. Categories to look for:
+
+- **UI changes** — new screens, modified layouts, changed interactions, error states
+- **CLI/terminal output** — new commands, changed output, new flags or options
+- **API responses** — new endpoints, changed payloads, different status codes
+- **State changes** — database records, file system artifacts, config effects
+- **Error paths** — bad input, missing dependencies, edge conditions
+
+For each observable behavior, determine:
+
+1. **What to do** — the specific action (command to run, button to click, request to send)
+2. **What to expect** — the observable result that confirms the change works
+3. **Why bother** — one phrase connecting this observation to the change's intent (omit if obvious from context)
+
+Target 2–5 suggestions for a typical change. If more than 5 qualify, prioritize by how much confidence the observation provides relative to effort. A change with zero observable behavior is fine — do not pad with trivial observations.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → Detail Pass → [Testing]
+```
+
+Then the testing suggestions using this format:
+
+```
+### How to See It Working
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+```
+
+Include code blocks for commands or requests where helpful.
+
+If the change has no observable behavior, replace the suggestions with:
+
+```
+### How to See It Working
+
+This change is internal — no user-visible behavior to observe. The diff and tests tell the full story.
+```
+
+### Closing
+
+End the message with:
+
+```
+---
+
+You've seen the change and how to verify it. When you're ready to make a call, just say so.
+```
+
+## NEXT
+
+When the human signals they're ready to make a decision about this {change_type}, read fully and follow `./step-05-wrapup.md`

package/skills/sdlc/bmad-checkpoint-preview/step-05-wrapup.md

@@ -0,0 +1,24 @@
+# Step 5: Wrap-Up
+
+Display: `Orientation → Walkthrough → Detail Pass → Testing → [Wrap-Up]`
+
+## Follow Global Step Rules in SKILL.md
+
+## PROMPT FOR DECISION
+
+```
+---
+
+Review complete. What's the call on this {change_type}?
+- **Approve** — ship it (I can help with interactive patching first if needed)
+- **Rework** — back to the drawing board (revert, revise the spec, try a different approach)
+- **Discuss** — something's still on your mind
+```
+
+HALT — do not proceed until the user makes their choice.
+
+## ACT ON DECISION
+
+- **Approve**: Acknowledge briefly. If the human wants to patch something before shipping, help apply the fix interactively. If reviewing a PR, offer to approve via `gh pr review --approve` — but confirm with the human before executing, since this is a visible action on a shared resource.
+- **Rework**: Ask what went wrong — was it the approach, the spec, or the implementation? Help the human decide on next steps (revert commit, open an issue, revise the spec, etc.). Help draft specific, actionable feedback tied to `path:line` locations if the change is a PR from someone else.
+- **Discuss**: Open conversation — answer questions, explore concerns, dig into any aspect. After discussion, return to the decision prompt above.

package/skills/sdlc/bmad-correct-course/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-correct-course
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
+---
+
+Follow the instructions in ./workflow.md.

package/skills/sdlc/bmad-correct-course/checklist.md

@@ -0,0 +1,288 @@
+# Change Navigation Checklist
+
+<critical>This checklist is executed as part of: ./workflow.md</critical>
+<critical>Work through each section systematically with the user, recording findings and impacts</critical>
+
+<checklist>
+
+<section n="1" title="Understand the Trigger and Context">
+
+<check-item id="1.1">
+<prompt>Identify the triggering story that revealed this issue</prompt>
+<action>Document story ID and brief description</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.2">
+<prompt>Define the core problem precisely</prompt>
+<action>Categorize issue type:</action>
+  - Technical limitation discovered during implementation
+  - New requirement emerged from stakeholders
+  - Misunderstanding of original requirements
+  - Strategic pivot or market change
+  - Failed approach requiring different solution
+<action>Write clear problem statement</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.3">
+<prompt>Assess initial impact and gather supporting evidence</prompt>
+<action>Collect concrete examples, error messages, stakeholder feedback, or technical constraints</action>
+<action>Document evidence for later reference</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
+</halt-condition>
+
+</section>
+
+<section n="2" title="Epic Impact Assessment">
+
+<check-item id="2.1">
+<prompt>Evaluate current epic containing the trigger story</prompt>
+<action>Can this epic still be completed as originally planned?</action>
+<action>If no, what modifications are needed?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.2">
+<prompt>Determine required epic-level changes</prompt>
+<action>Check each scenario:</action>
+  - Modify existing epic scope or acceptance criteria
+  - Add new epic to address the issue
+  - Remove or defer epic that's no longer viable
+  - Completely redefine epic based on new understanding
+<action>Document specific epic changes needed</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.3">
+<prompt>Review all remaining planned epics for required changes</prompt>
+<action>Check each future epic for impact</action>
+<action>Identify dependencies that may be affected</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.4">
+<prompt>Check if issue invalidates future epics or necessitates new ones</prompt>
+<action>Does this change make any planned epics obsolete?</action>
+<action>Are new epics needed to address gaps created by this change?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.5">
+<prompt>Consider if epic order or priority should change</prompt>
+<action>Should epics be resequenced based on this issue?</action>
+<action>Do priorities need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="3" title="Artifact Conflict and Impact Analysis">
+
+<check-item id="3.1">
+<prompt>Check PRD for conflicts</prompt>
+<action>Does issue conflict with core PRD goals or objectives?</action>
+<action>Do requirements need modification, addition, or removal?</action>
+<action>Is the defined MVP still achievable or does scope need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.2">
+<prompt>Review Architecture document for conflicts</prompt>
+<action>Check each area for impact:</action>
+  - System components and their interactions
+  - Architectural patterns and design decisions
+  - Technology stack choices
+  - Data models and schemas
+  - API designs and contracts
+  - Integration points
+<action>Document specific architecture sections requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.3">
+<prompt>Examine UI/UX specifications for conflicts</prompt>
+<action>Check for impact on:</action>
+  - User interface components
+  - User flows and journeys
+  - Wireframes or mockups
+  - Interaction patterns
+  - Accessibility considerations
+<action>Note specific UI/UX sections needing revision</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.4">
+<prompt>Consider impact on other artifacts</prompt>
+<action>Review additional artifacts for impact:</action>
+  - Deployment scripts
+  - Infrastructure as Code (IaC)
+  - Monitoring and observability setup
+  - Testing strategies
+  - Documentation
+  - CI/CD pipelines
+<action>Document any secondary artifacts requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="4" title="Path Forward Evaluation">
+
+<check-item id="4.1">
+<prompt>Evaluate Option 1: Direct Adjustment</prompt>
+<action>Can the issue be addressed by modifying existing stories?</action>
+<action>Can new stories be added within the current epic structure?</action>
+<action>Would this approach maintain project timeline and scope?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.2">
+<prompt>Evaluate Option 2: Potential Rollback</prompt>
+<action>Would reverting recently completed stories simplify addressing this issue?</action>
+<action>Which stories would need to be rolled back?</action>
+<action>Is the rollback effort justified by the simplification gained?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.3">
+<prompt>Evaluate Option 3: PRD MVP Review</prompt>
+<action>Is the original PRD MVP still achievable with this issue?</action>
+<action>Does MVP scope need to be reduced or redefined?</action>
+<action>Do core goals need modification based on new constraints?</action>
+<action>What would be deferred to post-MVP if scope is reduced?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.4">
+<prompt>Select recommended path forward</prompt>
+<action>Based on analysis of all options, choose the best path</action>
+<action>Provide clear rationale considering:</action>
+  - Implementation effort and timeline impact
+  - Technical risk and complexity
+  - Impact on team morale and momentum
+  - Long-term sustainability and maintainability
+  - Stakeholder expectations and business value
+<action>Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid]</action>
+<action>Justification: [Document reasoning]</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="5" title="Sprint Change Proposal Components">
+
+<check-item id="5.1">
+<prompt>Create identified issue summary</prompt>
+<action>Write clear, concise problem statement</action>
+<action>Include context about discovery and impact</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.2">
+<prompt>Document epic impact and artifact adjustment needs</prompt>
+<action>Summarize findings from Epic Impact Assessment (Section 2)</action>
+<action>Summarize findings from Artifact Conflict Analysis (Section 3)</action>
+<action>Be specific about what changes are needed and why</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.3">
+<prompt>Present recommended path forward with rationale</prompt>
+<action>Include selected approach from Section 4</action>
+<action>Provide complete justification for recommendation</action>
+<action>Address trade-offs and alternatives considered</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.4">
+<prompt>Define PRD MVP impact and high-level action plan</prompt>
+<action>State clearly if MVP is affected</action>
+<action>Outline major action items needed for implementation</action>
+<action>Identify dependencies and sequencing</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.5">
+<prompt>Establish agent handoff plan</prompt>
+<action>Identify which roles/agents will execute the changes:</action>
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
+  - Product Manager / Architect (for strategic changes)
+<action>Define responsibilities for each role</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="6" title="Final Review and Handoff">
+
+<check-item id="6.1">
+<prompt>Review checklist completion</prompt>
+<action>Verify all applicable sections have been addressed</action>
+<action>Confirm all [Action-needed] items have been documented</action>
+<action>Ensure analysis is comprehensive and actionable</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.2">
+<prompt>Verify Sprint Change Proposal accuracy</prompt>
+<action>Review complete proposal for consistency and clarity</action>
+<action>Ensure all recommendations are well-supported by analysis</action>
+<action>Check that proposal is actionable and specific</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.3">
+<prompt>Obtain explicit user approval</prompt>
+<action>Present complete proposal to user</action>
+<action>Get clear yes/no approval for proceeding</action>
+<action>Document approval and any conditions</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.4">
+<prompt>Update sprint-status.yaml to reflect approved epic changes</prompt>
+<action>If epics were added: Add new epic entries with status 'backlog'</action>
+<action>If epics were removed: Remove corresponding entries</action>
+<action>If epics were renumbered: Update epic IDs and story references</action>
+<action>If stories were added/removed: Update story entries within affected epics</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.5">
+<prompt>Confirm next steps and handoff plan</prompt>
+<action>Review handoff responsibilities with user</action>
+<action>Ensure all stakeholders understand their roles</action>
+<action>Confirm timeline and success criteria</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
+</halt-condition>
+
+</section>
+
+</checklist>
+
+<execution-notes>
+<note>This checklist is for SIGNIFICANT changes affecting project direction</note>
+<note>Work interactively with user - they make final decisions</note>
+<note>Be factual, not blame-oriented when analyzing issues</note>
+<note>Handle changes professionally as opportunities to improve the project</note>
+<note>Maintain conversation context throughout - this is collaborative work</note>
+</execution-notes>