Dev Issue

Full Issue Lifecycle (HMIS)

Invoking this skill is the explicit authorization for every commit/push/PR step below — do not re-ask before each one. Discussion gates (steps 2a non-repro case and any state-changing step taken there to prove an unconfirmed bug, 3, 4's environment choice only, 14) are the points where you pause for the user. Everything else in 2a and 4 (which department/record to use against local test data) is a local-testing-environment choice, not a product decision — decide it yourself and say what you picked, rather than pausing.

That 2a gate is narrow and does not extend to step 7. 2a's risk is spending effort chasing a bug that might not be real; once step 3 has been through Plan Mode and the user has approved a fix, that risk is gone — exercising the approved fix in step 7, including any state-changing UI action needed to set up the scenario (e.g. removing a room, changing a status, editing a record) against local test data, is the same no-need-to-ask local-testing-environment judgment call as picking which department/record to use. Decide it yourself, do it through the real app UI (never raw SQL for setup — see step 7), and report exactly what you did as evidence. Only ask first if the action would reach outside local test data (a remote environment, or anything step 4's environment-choice gate already covers).

This authorization also covers superpowers:writing-plans' Execution Handoff question, if that chain gets invoked anywhere in this flow (e.g. during step 5): auto-select option 1, Subagent-Driven without asking — do not stop for it as an additional discussion gate.

0. Anything you write to GitHub is public

hmislk/hmis is a public repo. Before every gh issue create, gh issue comment, gh pr create or gh pr comment in the steps below, apply What May Go Into a GitHub Issue, PR, or Comment: no patient/doctor/staff names, production record identifiers (bill/BHT/PHN numbers, entity IDs), affected-record counts, production schema names, cutover dates, per-staff statistics, data-fix logs or credentials. Describe the defect and the local test evidence; keep hospital-specific numbers in tmp/. This applies to the issue body as much as to the PR — including an issue you file mid-run for a bug you found yourself.

1. Setup

Run the start-issue skill for $0: creates the branch from origin/development, sets persistence.xml to local JNDI, assigns the issue, sets the project board status to In Progress.

2. Investigate

• Read the issue body and comments (gh issue view $0 --comments).
• Explore the relevant code. Use the Explore agent for anything spanning more than a few files.
• Identify: which entities/services/JSF pages are involved, which existing patterns to follow (DTOs, privileges, AJAX), and what's actually broken or missing.
• If the issue is a bug report, try to pin down the root cause by reading code first. Note explicitly whether this succeeded — that decides whether step 2a runs.

2a. Reproduce the bug (bug issues only)

Skip this step for feature/enhancement issues, and for bug issues where step 2's code reading already found a clear, confirmed root cause.

Run it when the issue is a bug and step 2 left the cause unconfirmed or unfound:

• Prefer reproducing against existing data first (read-only navigation or API GETs) — picking which department/record to read is the same no-need-to-ask judgment call as step 4. If reproduction requires a state-changing step (creating, modifying, or deleting a record, or running direct SQL), that's a different risk category: confirm with the user first (AskUserQuestion) before creating a disposable record, modifying/deleting an existing record, or running direct SQL — don't extend the "don't ask" judgment call to writes. If the user approves a disposable record, clean it up in the same session where possible.
• Reproduce live against local Payara — the playwright-e2e skill for UI-facing bugs, or direct REST calls (per api-development) for API-only ones.
• Save "before" evidence into the project tmp/ folder: screenshots for UI bugs, request/response bodies for API bugs. Redact patient identifiers, credentials, tokens, cookies, and other sensitive fields from any saved API body before it leaves tmp/.
  • If it reproduces, this evidence proves the bug and becomes the "before" half of the before/after comparison published in step 10.
  • If it does not reproduce, record that — under the tested environment, data, and inputs — the bug did not reproduce; that is not proof the bug is absent. Stop here, post the finding to the issue, and confirm with the user whether to still proceed (per CLAUDE.md "discuss uncertainties") rather than guessing at a fix for a bug you couldn't observe.

3. Discuss the approach (Plan Mode)

Enter Plan Mode. Present:

• What you found in step 2 (and step 2a's reproduction evidence, for bugs)
• The proposed change (files to touch, approach)
• Anything uncertain (per CLAUDE.md rule "discuss uncertainties")

Exit Plan Mode only once the user approves or adjusts the plan.

4. Gather test context

Local Payara / local DB is a testing environment — pick department and records yourself rather than gating on the user for them:

• Department: query the local DB for one that's real and relevant to the feature (e.g. Pharmacy, Inward, OPD), and say which one you picked before testing.
• Specific records to exercise (e.g. an admission ID, bill number, item code): query the local DB for existing records that fit the feature and use those — report exactly which ones you used (BHT no, bill no, etc.) in the PR/issue evidence. Only ask the user if the local DB has no suitable record at all (e.g. the feature needs a state nothing local is in) — that is a real blocker, not a preference question.
• Environment: local Payara (default) unless the issue specifically requires testing against a remote env, in which case confirm which one with the user (this one is a real decision — remote envs carry real data/credentials risk that local doesn't). Credentials live outside the repo in C:\Credentials\ — never inlined.

Only the environment choice is a discussion gate here. Department/record selection against local test data is not — deciding it yourself and moving straight to step 5 keeps this step from wasting a round-trip on a question that has no wrong answer in a disposable local DB.

5. Develop

Delegate implementation by file type, per CLAUDE.md module rules (DTOs, JPQL-first, privilege system, AJAX update rules, etc.):

• Java entities/services/DTOs/REST → java-backend-developer agent
• XHTML/PrimeFaces views → jsf-frontend-dev agent
• Mixed changes: split into per-area tasks and delegate each

Review the diffs from each agent before moving on — don't trust a summary without checking the actual edits.

5a. Regenerate the DDL if the schema changed

If step 5 added or renamed any entity field, or added a new entity/table, run the generate-ddl skill before moving on. This keeps tmp/createDDL.jdbc and the Database-Schema-DDL-Generation-Guide wiki page in sync with the actual schema, so other developers and fresh installs can pick up the new column/table without hand-writing a migration. Skip this step entirely if the issue only changed business logic with no new persisted fields.

6. Build and local redeploy ("deploy sos")

Per playwright-e2e §0a:

$env:JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-11.0.23.9-hotspot"
& "D:\Program Files\NetBeans-18\netbeans\java\maven\bin\mvn.cmd" clean package -DskipTests
& "D:\Payara\bin\asadmin.bat" redeploy --name rh "D:\Development\2024\hmis\target\rh-3.0.0.war"

Check D:\Payara\glassfish\domains\domain1\logs\server.log for deployment errors before moving on.

7. Test with Playwright + verify in DB

Run the playwright-e2e skill workflow:

• Login, select the department from step 4
• If verifying the fix requires putting a record into a specific state first (e.g. a race-condition fix needs a room removed, a status changed, a second record created), do that live through the real app UI yourself — this is the same local-testing-environment judgment call as step 4's department/record choice, not a fresh discussion gate. (Unlike step 2a, which gates state-changing actions because it's proving an unconfirmed bug, step 7 is exercising a fix the user already approved in step 3.) Report exactly what you did (menu path, record IDs, before/after DB state) as part of the evidence.
• Navigate to the page through the menus, never by URL — HMIS page state is set by the @SessionScoped navigation method, so a URL-loaded page renders against uninitialised state and produces false findings (playwright-e2e §2). Record the menu path in the issue/PR.
• Exercise the feature using the records chosen in step 4
• Take screenshots (browser_take_screenshot) into the project tmp/ folder at each meaningful stage (before/after states, confirmation dialogs, final result) — per playwright-e2e §0. These double as evidence for the issue/PR and wiki in step 10. For bug issues where step 2a ran, capture the same view/state it reproduced, so it pairs cleanly as the "after" half of that before/after comparison. For API-only bugs, replay the original request (the actual parameters, not the redacted evidence artifact) against the same confirmed target instead. If that request mutates state, reuse a resettable/disposable target or get the user's confirmation again before replaying it — don't apply a write twice against real data just to capture evidence. Save the response status/body (redacted, same rule as step 2a) as the "after" evidence.
• Verify the result in the local DB (credentials: see the local_mysql_credentials.md memory)

8. Iterate

If the test reveals a bug: fix the code (step 5), rebuild/redeploy (step 6), retest (step 7). Repeat until the flow passes end-to-end.

9. Record learnings

If a new Playwright/dev gotcha surfaced, add it to the matching topic file in developer_docs/testing/playwright-e2e/. Number it after the highest § in use, and list it in the main guide's Contents. Write it as a symptom heading plus 1–3 lines of fix. Leave the story, dates and issue history out; they belong in the PR. Skip this step if nothing new came up.