@solaqua/ghosts 0.2.0 → 0.2.2

package/engineering/skills/grill-me/README.md

@@ -0,0 +1,11 @@
+# Grill Me
+
+An interview that stress-tests a plan, decision, or idea through question rounds
+ordered by their dependencies, ending with a short, grouped decision summary.
+
+## Credits
+
+Shout-out to [Matt Pocock](https://github.com/mattpocock) for the original
+[grilling skill](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md).
+This adaptation keeps its interview flow and adds guidance for a concise,
+readable result summary.

package/engineering/skills/grill-me/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: grill-me
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking or asks to be grilled.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map
+this as a design tree: every decision branches into the decisions that depend
+on it.
+
+Work the tree in rounds. The frontier is every decision whose prerequisites
+are already settled: questions you can ask now without guessing at answers you
+have not heard yet. Ask the whole frontier in one round, number each question,
+and give your recommended answer. Then wait for the user's answers.
+
+Format a round like this:
+
+```md
+❓ **Q1** - **<Question title>**: <Question, with choices when useful>
+
+➡️ <Recommended answer>
+
+---
+
+❓ **Q2** - **<Question title>**: <Question, with choices when useful>
+
+➡️ <Recommended answer>
+```
+
+Each round reshapes the tree. Settled decisions unblock their dependent
+questions; recompute the frontier and ask the next round. A question depending
+on another question still open in this round belongs to a later round.
+
+Finding facts is your job, never the user's. When a question needs a fact from
+the environment, dispatch a subagent to find it. A running exploration is an
+unsettled prerequisite: only downstream questions wait; ask the rest of the
+frontier now. The decisions are the user's: put each to them and wait.
+
+The session is done when every branch within scope is resolved and nothing
+remains silently assumed. An empty frontier while research is pending is not
+completion. Do not act until the user confirms the shared understanding.
+
+Present the result using this template in the user's language. Replace
+placeholders, repeat decision groups as needed, and omit constraints when none:
+
+```md
+## Outcome
+
+<Agreed goal and direction in 1–2 sentences>
+
+## Decisions
+
+### <Related decision group>
+
+- <Agreed choice and its key reason or accepted trade-off>
+
+## Constraints
+
+- <Material scope boundary or constraint>
+
+Does this capture our shared understanding?
+```
+
+Keep it readable in one screen without scrolling. Include only what someone
+needs to understand the result; omit the interview transcript, question IDs,
+and full decision tree. Use a compact table or diagram only when it makes the
+decisions easier to understand.

package/engineering/skills/loop-plan/SKILL.md

@@ -58,7 +58,7 @@ fixed ceremony.
 ```text
 [Understand] → [Route unknowns]
                   ├─ evidence → [$loop-research] ┐
-                  ├─ user decision → [$socratic-interview] ├→ [Frame + ledger] → [Draft]
+                  ├─ user decision → [$grill-me] ├→ [Frame + ledger] → [Draft]
                   └─ known →─────────────────────┘              ↓
                                                      [Any high-impact uncertainty?]
                                                        ├─ No → [Self challenge]
@@ -136,20 +136,20 @@ Route unresolved inputs before making design decisions. Use `$loop-research` for
 repository or document investigation, current or contested evidence,
 comparisons, feasibility checks, or source citations; it returns verified
 claims, provenance, uncertainty, and leads that could change the plan. Use
-`$socratic-interview` for choices only the user can make, such as outcome,
-scope, priority, risk tolerance, or external action; it asks one focused
-question at a time and returns an execution brief, but does not plan or edit.
-Do not ask the user for facts inspection or research can establish, and do not
-replace a user decision with an inferred preference. Carry both outputs into
-the decision ledger.
-
-Ask the smallest question when an unknown could change scope, success, or a
-costly decision; continue independent inspection while waiting. State ordinary
-assumptions and proceed. If feasibility remains unestablished, put the cheapest
-useful investigation first with a decision criterion and keep dependent work
-conditional rather than inventing certainty. State task-specific principles,
-rank decision drivers, resolve conflicts explicitly, and define observable
-success before choosing.
+`$grill-me` for choices only the user can make, such as outcome, scope, priority,
+risk tolerance, or external action. It asks the whole ready frontier in each
+round and returns a short, grouped decision summary. Wait for the user to confirm
+the shared understanding before carrying its decisions into the plan. Do not
+ask the user for facts that inspection or research can establish, or infer a
+material preference. Carry both outputs into the decision ledger.
+
+Resolve material user choices through the interview's dependency-aware rounds;
+continue independent inspection while waiting. State ordinary assumptions only
+when they do not replace a material user decision. If feasibility remains
+unestablished, put the cheapest useful investigation first with a decision
+criterion and keep dependent work conditional rather than inventing certainty.
+State task-specific principles, rank decision drivers, resolve conflicts
+explicitly, and define observable success before choosing.
 
 ## Compare and draft
 

package/engineering/skills/test-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: test-review
+description: Read-only review of tests in a change, PR, or path against shared, frontend, and backend testing standards.
+disable-model-invocation: true
+---
+
+# Test Review
+
+Review the tests read-only. If no target is given, review the tests in the current branch's diff against the base branch. Write in the user's language.
+
+Always apply [references/common.md](references/common.md). Add [references/frontend.md](references/frontend.md) for UI or browser tests and [references/backend.md](references/backend.md) for server, worker, or data tests; use both when the change spans them. For another stack, apply only `common.md`.
+
+1. Map each changed behavior to the existing and new tests that protect it. Flag behavior no test would catch if it broke, and removed tests whose protection is not covered elsewhere.
+2. Review each added, changed, or removed test against the guides' review checklists.
+3. Keep only findings with a location, a concrete failure scenario, and a guide rule behind them. Running existing tests to confirm a finding is allowed; editing code or tests is not.
+
+Prioritize findings:
+
+- `P1`: a changed behavior has no test that would fail if it broke, or a test cannot fail for the regression it claims to catch.
+- `P2`: implementation coupling, test doubles replacing the behavior under test, nondeterminism, leaking state, or redundant protection.
+- `P3`: naming, structure, or readability.
+
+Write the review following [templates/review.md](templates/review.md), replacing each placeholder or omitting the section as it directs.

package/engineering/skills/test-review/references/backend.md

@@ -0,0 +1,280 @@
+# Backend Testing Guide
+
+This document defines the shared testing standards for backend teams. Tests are not written just to see `Pass`. They are written to fail quickly and clearly when important behavior is broken.
+
+Repository structure, fixture names, and test commands may differ by repository. This guide focuses on shared judgment criteria for writing and reviewing backend tests, rather than repository-specific usage.
+
+## 1. Testing Philosophy
+
+### 1.1 Meaningful Failure
+
+- A test should fail when the behavior it protects is broken.
+- A test that keeps passing after a requirement change or bug does not provide safety. It only adds maintenance cost.
+- If a refactor breaks a test while observable behavior remains the same, the test is likely coupled too tightly to implementation details.
+- Regression tests and snapshot tests are useful when they protect contracts that must not change accidentally.
+- If a test failure does not reveal which requirement was broken, improve the test name, setup, or assertions.
+
+### 1.2 Choose Test Targets By Value
+
+Apply [Test Target Value](common.md#test-target-value), and:
+
+- When an integration test already protects a behavior, do not automatically repeat it in unit tests for every participating layer. Add focused tests where they provide additional protection or clearer checks of important edge cases.
+
+High-priority targets:
+
+- Business-critical flows such as payment, authentication, authorization, subscriptions, and event publishing
+- Tasks and workers that are expensive to recover from when they fail
+- Complex queries, pagination, cursors, ordering, locks, and idempotency
+- Logic that interprets external system responses and mutates local state
+- Edge-case-heavy logic such as dates, timezones, market holidays, exchange rates, decimals, and discounts
+
+Lower-priority targets:
+
+- Simple getters, setters, and DTO declarations
+- Behavior already guaranteed by the library
+- Shape errors that static analysis, type checkers, or linters catch better
+- Tests that only repeat the implementation without improving behavioral safety
+
+## 2. Test Scope Strategy
+
+Prefer tests that keep the real collaboration needed to deliver a feature intact. A test can exercise an API, service, repository, and DB together while protecting one clearly defined behavior. The number of participating components and the number of concerns being tested are separate choices.
+
+Apply [Focused Scenarios](common.md#focused-scenarios).
+
+Recommended approach:
+
+1. First check whether the behavior can be tested through an existing public entrypoint from the perspective of a user or external system. Do not expand production interfaces solely for testing convenience.
+2. Prefer integration tests when API, service, repository, DB, and cache behavior can be verified together clearly.
+3. Narrow the scope one level when the integration test becomes too slow, too hard to set up, or too hard to debug.
+4. Use unit tests directly for naturally small units such as pure calculations, parsers, and validators.
+5. Replace external systems we do not control at the test boundary, such as third-party APIs, payment providers, email, and object storage.
+
+Why we prefer larger tests:
+
+- They catch real wiring, transaction, serialization, and dependency override issues.
+- They remain stable when internal calls change but the feature behavior stays the same.
+- They produce a signal closer to production behavior than tests with heavy mocking.
+
+When to narrow the scope:
+
+- The setup is so large that the important condition is hard to see.
+- The failure cause is difficult to isolate.
+- Replacing external dependencies takes up most of the test.
+- Slow tests start hurting the feedback loop.
+- One complex rule needs many focused edge-case checks.
+
+## 3. Test Naming And Grouping
+
+Test names should reveal both the situation and the expected outcome.
+
+Basic rules:
+
+- Use `test_<situation>_<expected_outcome>` for test function names.
+- Every test should have a docstring.
+- For complex tests, use the docstring to describe the requirement or intent more specifically.
+- Prefer capability- and outcome-oriented names over implementation-shaped names.
+- Describe what the test actually exercises and observes. Do not claim to verify behavior that has been replaced by a test double.
+- Use `pytest.mark.parametrize` with readable `ids` for cases of the same behavior that share an execution flow. Split cases when combining them introduces branches that obscure their different scenarios.
+
+Example:
+
+```python
+async def test_expired_subscription_removes_user_role(...) -> None:
+    """An expired subscription removes the user's role."""
+```
+
+Avoid implementation-shaped names:
+
+```python
+async def test_calls_delete_role(...) -> None:
+    ...
+```
+
+### 3.1 Class Grouping
+
+Use classes when related tests are easier to read as one group. Standalone test functions are appropriate when grouping adds no clarity.
+
+- Group tests by feature or public entrypoint.
+- Do not use classes to hide important setup or build complex lifecycles.
+- Each test inside the class should still be understandable on its own.
+
+## 4. AAA Pattern
+
+Write test bodies in the `given / when / then` flow.
+
+- `given`: Data, fixtures, mocks, and fixed time required for the scenario
+- `when`: The behavior under test
+- `then`: Observable results of `when`, such as the response, DB state, events, and external calls
+
+Example:
+
+```python
+async def test_expired_subscription_removes_user_role(...) -> None:
+    """An expired subscription removes the user's role."""
+    # given
+    subscription = create_subscription(status="active", expired=True)
+
+    # when
+    await expire_subscriptions()
+
+    # then
+    assert not user_has_role(subscription.user_id, "premium")
+```
+
+Notes:
+
+- If `when` contains several independent actions, it becomes unclear which action caused the failure.
+- One test may verify multiple results, but they should all come from the same behavior.
+- Use helpers when setup becomes long, but keep the important scenario conditions visible in the test body.
+
+## 5. Layer-Specific Guidelines
+
+Use the largest layer that still gives a clear signal.
+
+- API tests are a good default when behavior is observable through HTTP. Verify the response contract and important side effects.
+- Service or domain tests are useful when the business rule is the main concern and an API test would be too heavy.
+- Repository or DAO behavior is usually covered through a higher-level test. Test it directly only when the query contract itself is the main risk.
+- Task and worker tests should focus on operational concerns such as duplicate handling, retries, partial failures, and idempotency.
+- Avoid API loops for large setup. Insert data directly or use helpers/factories when setup is not the behavior under test.
+
+## 6. Fixture And Test Data
+
+Fixtures are tools for readability. They should not hide the important conditions of a test.
+
+Good fixtures:
+
+- Hide repeated infrastructure setup.
+- Provide common dependencies such as DB sessions, clients, caches, repositories, and services.
+- Make their provided state clear from the name.
+
+Fixtures to be careful with:
+
+- Fixtures that automatically create too many rows and make test conditions hard to trace.
+- Fixtures that hide the core condition of a scenario.
+- Fixtures that accept many scenario-specific parameters and become a small DSL.
+- Deep fixture dependency chains that make failures hard to diagnose.
+
+Recommended approach:
+
+- Promote helpers or fixtures to a shared place when multiple domains reuse them.
+- Keep domain-specific helpers near that domain.
+- Keep scenario-specific core conditions in the test body.
+- Reuse established setup helpers when their behavior is outside the test's concern.
+- Extract helpers to make scenarios easier to understand, not just to remove repeated lines. A little duplication is preferable to an abstraction that hides the important conditions or execution flow.
+- Use helper and factory names that reveal intent. Examples: `create_expired_subscription`, `create_verified_user`
+- Create only the minimum rows required by the test.
+
+### 6.1 DB Setup
+
+- Isolate DB changes with transaction rollback whenever possible.
+- Use `flush` when DB-generated values or query-visible rows are needed.
+- Use `commit` only when verifying behavior that is visible only after commit, across separate transactions, or through task/worker entrypoints.
+- Do not clean tables manually in tests. Before adding cleanup fixtures, confirm why transaction rollback cannot solve the problem.
+- Prefer DB bulk inserts over API loops for large setup.
+
+### 6.2 Cache And External State
+
+- Prefer shared fixtures for cache cleanup, dependency overrides, monkeypatches, and environment overrides.
+- Do not repeat cleanup setup in individual tests when the repository already handles it globally.
+- Verify cache keys, TTLs, and session values directly when they are part of the contract.
+
+## 7. Test Double Policy
+
+Use test doubles to move the external world and unstable inputs to the test boundary.
+
+Good targets for test doubles:
+
+- Payment providers, Google Play, Apple, Firebase, S3, Discord, email, and Kafka producers
+- Other servers or external HTTP clients
+- Current time, randomness, and UUIDs
+- Very slow or nondeterministic library calls
+
+Avoid replacing when possible:
+
+- Services, repositories, and DAOs in the same process
+- Internal helpers called by the function under test
+- Private properties or private methods
+- The DB session itself
+- The entire service behind an endpoint
+
+Guidelines:
+
+- Test doubles should make the test condition clearer.
+- If replacing internal collaborators makes the test fragile during refactoring, switch to a larger-scope test.
+- If a dependency is already mocked at an upper boundary, do not also mock the lower DAO unnecessarily.
+- Use `spec` or real-object-based `patch.object` for `Mock` and `AsyncMock` whenever possible.
+- Patch where the object is used, not where it is defined.
+
+Partial replacement can be better than replacing the whole object. For example, instead of replacing an entire external client, create the client through the real factory and patch only the failing method. This keeps more framework wiring intact.
+
+## 8. Time, Randomness, And Determinism
+
+Tests should produce the same result every time they run.
+
+- Freeze or patch the current time.
+- When timezone behavior matters, assert the base timezone, UTC conversion, and epoch values explicitly.
+- Use fixed values when randomness, UUIDs, or current time appear in DB values or responses.
+- For ordering-sensitive tests, make `created_at`, `id`, and cursor values explicit.
+- External API response fixtures should contain only the fields needed, but enough fields to represent the edge case.
+
+## 9. Assertions
+
+Good assertions make it clear what broke when the test fails.
+
+Recommended:
+
+- In API tests, assert `status_code` first.
+- Use snapshots or exact dictionaries when the whole response is the contract.
+- Assert only the important fields explicitly when only some fields are contractual.
+- Verify DB side effects by reading them back through a repository or query.
+- Assert downstream contracts directly, such as event payloads, unique keys, and published flags.
+- For lists, assert length, order, and important identifiers together.
+
+Avoid:
+
+- Assertions that provide little signal, such as `assert response.json() is not None`
+- Overly broad snapshots that fail on unrelated field changes
+- Tests that only assert mock call counts without verifying actual state changes
+- Recomputing the expected value with the same logic as the implementation under test
+
+## 10. Snapshot Usage
+
+Snapshots are useful when protecting large JSON responses or complex payload contracts.
+
+Use snapshots when:
+
+- The entire response structure is part of the API contract.
+- Volatile values are stabilized with matchers, fixed time, or fixed IDs.
+- Snapshot updates are intentional and reviewed in the same PR as the code change.
+- The diff is small enough for reviewers to understand.
+
+Avoid snapshots when:
+
+- Only a few fields matter.
+- The collection ordering is not stable.
+- Timestamps, UUIDs, or ordering change on every run.
+- The payload is so large that failures are hard to interpret.
+
+## 11. Coverage
+
+Coverage is a signal, not the quality goal itself.
+
+- Whether changed code protects important branches and failure cases matters more than total coverage.
+- If PR coverage is low, explain why the code does not need tests or which higher-level test covers it.
+- Use missing lines in the coverage report to find candidate test targets.
+- Do not add meaningless tests just to increase coverage.
+
+## 12. Review Checklist
+
+Apply the [Review Checklist](common.md#review-checklist), and check the implementation and remaining risks:
+
+- If the scope was narrowed, is the reason clear?
+- Do the name and docstring accurately describe what the test exercises and observes?
+- Is the `given / when / then` flow clear?
+- Can DB, cache, and dependency overrides leak between tests?
+- Are time, UUIDs, randomness, and ordering deterministic?
+- Are necessary failure, permission, and authentication cases covered?
+- Are backend-specific concerns such as pagination, cursors, idempotency, and transactions covered?
+- If a snapshot is used, can reviewers understand the diff?
+- If test doubles keep increasing, should the test move to a larger scope?
+- If fixtures hide too many conditions, should those conditions move back into the test body?

package/engineering/skills/test-review/references/common.md

@@ -0,0 +1,30 @@
+# Common Testing Standards
+
+Sections shared by [frontend.md](frontend.md) and [backend.md](backend.md).
+
+## Test Target Value
+
+Do not try to test all code at the same density. Evaluate the protection each test adds to the existing suite against the cost of writing, reading, running, and maintaining it. The goal is reliable protection of important behavior, not the fewest tests or the highest coverage number.
+
+- Before adding or retaining a test, identify the important regression it catches that existing tests do not adequately cover.
+- When a new feature reuses shared behavior, check what existing tests already protect. Add tests for how the feature uses that behavior and for any differences in its contract, rather than copying all tests for the shared behavior.
+- Before removing a test, confirm that important requirements and failure cases remain protected.
+
+## Focused Scenarios
+
+Keep each scenario focused on its intended behavior. Combine multiple actions when their sequence is itself the requirement, not merely because they can be placed in one workflow. Do not extend an existing test with unrelated assertions for a new feature when that behavior belongs in another test.
+
+## Review Checklist
+
+Start with the test's purpose and contribution to the suite:
+
+1. What important behavior does this test protect beyond the protection already provided by other tests?
+2. Does it contain only the setup, actions, and assertions needed for that behavior?
+3. Can a reader immediately understand the conditions, action, and expected outcome?
+
+Then check:
+
+- Would this test actually fail if that behavior broke?
+- Does it preserve useful collaboration between real components while keeping its concern focused?
+- Does the test verify externally observable behavior instead of internal implementation?
+- Do test doubles replace external or unstable dependencies without replacing the behavior under test?

package/engineering/skills/test-review/references/frontend.md

@@ -0,0 +1,301 @@
+# Frontend Testing Guide
+
+This guide defines the frontend testing standards our team uses when deciding what to test, how to structure tests, and which tradeoffs to make in this codebase.
+
+## 1. Testing Philosophy And Value
+
+### 1.1 Meaningful Failure
+
+Tests are not written just to see `Pass`. They should fail when the behavior they protect is broken.
+
+- A test that can keep passing after a meaningful regression does not improve safety. It only increases maintenance cost.
+- When requirements change or a bug is introduced, the test must fail and provide a signal.
+- Regression tests and snapshot tests are still valuable when they protect behavior that would fail after an unintended change.
+- If a test does not meaningfully fail for any realistic change, reconsider whether it should exist at all. In many cases, deleting it is the better choice.
+
+### 1.2 Value-Driven Target Selection
+
+Apply [Test Target Value](common.md#test-target-value), and:
+
+- When an integration test already protects a behavior, do not automatically repeat it in unit tests for every participating component or composable. Add focused tests where they provide additional protection or clearer checks of important edge cases.
+
+Prioritize behaviors that matter most to users and the business:
+
+- Core business logic
+  Example: payment, authentication
+- Complex data transformation logic
+- Utility functions with frequent edge cases
+
+## 2. Testing Strategy: Testing Trophy
+
+We follow Kent C. Dodds' `Testing Trophy` model, with the strongest emphasis on integration tests.
+
+Prefer tests that keep the real collaboration needed to deliver a feature intact. A test can exercise components, composables, and state management together while protecting one clearly defined behavior. The number of participating components and the number of concerns being tested are separate choices.
+
+Apply [Focused Scenarios](common.md#focused-scenarios).
+
+1. `Static (Lint/Type)`
+   Use TypeScript and ESLint to catch typos, type mismatches, and other basic mistakes. Do not duplicate test coverage for things that static analysis already verifies well.
+2. `Unit`
+   Verify highly complex calculations or isolated pure functions.
+3. `Integration`
+   This is our primary tactic. Verify whether multiple components work together to deliver a feature. Prefer sociable tests with minimal mocking.
+4. `E2E`
+   Verify user scenarios in a real browser environment.
+   Example: sign in -> search -> purchase
+   This is the safest level, but also the most expensive, so apply it only to critical paths.
+
+## 3. File Structure And Naming Conventions
+
+- Place specs for simple modules or component-local behavior next to the source file.
+- If a feature spans multiple components, place the spec under the feature's `tests/` directory or next to the representative entry component.
+- Even when the filename follows a representative component name, the test scope should cover the user-observable behavior delivered with its child components and composables.
+
+```text
+src/
+├── components/
+│   ├── BaseButton.vue
+│   ├── BaseButton.spec.ts
+│   └── Cart/
+│       ├── Cart.vue
+│       ├── CartRow.vue
+│       ├── useCart.ts
+│       └── tests/
+│           └── Cart.spec.ts
+└── utils/
+    ├── price.ts
+    ├── date.ts
+    └── tests/
+        ├── price.spec.ts
+        └── date.spec.ts
+```
+
+### `describe` Block Structure
+
+Use `describe` to show the shared subject of the tests, not the internal implementation structure. Keep it flat by default instead of nesting it.
+
+```tsx
+// Components / classes
+describe('Cart', () => {
+  it('수량을 증가시키면 총액이 재계산된다', () => {
+    // ...
+  });
+
+  it('수량은 1 미만으로 감소하지 않는다', () => {
+    // ...
+  });
+
+  it('삭제 버튼을 누르면 해당 상품이 목록에서 사라진다', () => {
+    // ...
+  });
+});
+
+// Public functions
+describe('formatPrice', () => {
+  it('정수를 원화 문자열로 변환한다', () => {
+    // ...
+  });
+});
+
+describe('applyDiscount', () => {
+  it('할인율만큼 차감된 금액을 반환한다', () => {
+    // ...
+  });
+});
+```
+
+- Name each `describe` block after the test target. Example: component name, hook name, public function name
+- Write each `it` or `test` block as a sentence that describes the expected outcome in that context.
+- Do not nest child `describe` blocks. If you need another context, split it into another top-level `describe` block instead.
+- Make test names specific enough to reveal both the situation and the expected result.
+- Prefer capability-oriented names over implementation-shaped names.
+  Example: `user can checkout with a valid cart` is better than `calls submitOrder with transformed payload`.
+- Describe what the test actually exercises and observes. Do not claim to verify behavior that has been replaced by a test double.
+- Use parameterized tests with readable case names for cases of the same behavior that share an execution flow. Split cases when combining them introduces branches that obscure their different scenarios.
+
+## 4. Test Writing Principles
+
+### 4.1 Black-box Tests
+
+Test externally observable behavior, not internal implementation details.
+
+- Do not read private properties or component-internal state directly.
+- Write tests from a black-box perspective. If input A is applied, does the user observe result B?
+- If a refactor breaks the test without changing behavior, the test was too coupled to the implementation.
+
+### 4.2 Avoid Designing Only For Tests
+
+Be careful not to damage production code readability or introduce unnecessary abstractions just to make tests easier to write.
+
+- First check whether the behavior can be verified through an existing public entrypoint before changing production code for testability.
+- Change the design only when the testing value clearly outweighs the design cost.
+- In most cases, improving a function interface is better than making the design more complex for testability.
+
+## 5. Practical Guide
+
+### 5.1 AAA Pattern
+
+For consistency, every test follows the `AAA (Given-When-Then)` pattern, and each section is marked with comments.
+
+- `Given`: Initial state, dependencies, test doubles, and fixed inputs required for the scenario
+- `When`: The behavior under test
+- `Then`: Observable results of `When`, such as rendered UI, user-visible state, and outgoing requests or events
+
+One test may verify multiple results, but they should all come from the same behavior.
+
+```tsx
+it('상품 수량을 변경하면 장바구니 총액이 재계산된다', async () => {
+  // Given
+  const product = { id: 1, name: 'T-Shirt', price: 10000 };
+
+  render(Cart, {
+    props: {
+      initialItems: [{ ...product, quantity: 1 }],
+    },
+  });
+
+  // When
+  const incrementButton = screen.getByRole('button', { name: /increase quantity/i });
+  await userEvent.click(incrementButton);
+
+  // Then
+  expect(screen.getByText(/total: 20,000 KRW/i)).toBeInTheDocument();
+});
+```
+
+Add supporting comments when they improve readability.
+
+```tsx
+it('쿠폰을 적용하면 최소 주문 금액 조건을 만족할 때만 할인 금액이 반영된다', async () => {
+  // Given: 장바구니 총액은 30,000원이고, 5,000원 할인 쿠폰은 최소 주문 금액 50,000원이 필요하다.
+  // 따라서 초기 상태에서는 쿠폰을 선택해도 할인은 적용되면 안 된다.
+
+  // When: 사용자가 수량을 늘려 총액을 50,000원 이상으로 만든 뒤 같은 쿠폰을 적용하면.
+
+  // Then: 할인 금액이 반영되고, 주문 요약 영역에 최종 결제 금액이 다시 계산되어 보여야 한다.
+});
+```
+
+### 5.2 Mocking Policy
+
+Limit mocking to the external world that we do not control. Compared with unit tests that heavily mock internal collaborators, integration tests with real collaboration boundaries are more resilient to refactoring and more trustworthy from the user's perspective.
+
+- Mock API calls at the network boundary with `MSW (Mock Service Worker)` instead of mocking server logic directly.
+- Prefer testing the integrated state where parent and child components actually collaborate.
+
+#### 5.2.1 Shared MSW Testing Standard
+
+For MSW-based tests, do not repeat the same setup in every spec. Build tests on top of a shared test environment, then override only the conditions required for the scenario with `server.use(...)`.
+
+- Control behavior at the network boundary.
+- Do not default to fine-grained `vi.mock()` calls against internal composables or API modules.
+- Write overrides so that they reveal only the condition the test is trying to validate.
+- Prefer helpers with obvious intent over large and noisy fixture payloads.
+
+#### 5.2.2 Shared Assumptions For Component Tests
+
+Reuse established setup helpers for dependencies outside the test's concern. For example, query client, store, injectables, and browser storage are usually better provided by the default test environment than recreated in each spec.
+
+Keep scenario-specific conditions and the execution flow visible in the test body. Extract helpers to make scenarios easier to understand, not just to remove repeated lines. A little duplication is preferable to an abstraction that hides those details.
+
+#### 5.2.3 Test Double Usage Standard
+
+In black-box component tests, keep real rendering whenever possible.
+
+- Do not increase test double usage just to make the test easier to write.
+- Consider stubs, spies, or mocks only when unrelated side effects make the test unstable or too noisy.
+- If a test double is necessary, its reason should be easy to explain.
+
+### 5.3 Async UI Waiting Principles
+
+In component tests, the synchronization point should not be "has the request finished?" It should be "has the DOM reached the state the user is supposed to see?"
+
+- Wait for appearance with `findBy*`.
+- Wait for disappearance with `waitForElementToBeRemoved`.
+- Use `waitFor(() => expect(...))` only when `findBy*` or dedicated removal APIs cannot express the expectation cleanly.
+- If `waitFor` is required, keep only one assertion inside the callback.
+
+`findBy*`, `waitFor`, and `waitForElementToBeRemoved` do not wait forever. They fail if the condition is not satisfied within the default timeout. Increase the timeout only when the specific test needs it.
+
+### 5.4 Handling Non-Deterministic Inputs
+
+Move unstable values such as current time or randomness to the test boundary.
+
+```ts
+// Before
+const getDeadline = () => {
+  const now = new Date();
+  return addDays(now, 7);
+};
+
+// After
+const getDeadline = (baseDate = new Date()) => {
+  return addDays(baseDate, 7);
+};
+
+it('마감일은 기준일로부터 7일 후다', () => {
+  const fixedDate = new Date('2024-01-01');
+  expect(getDeadline(fixedDate)).toEqual(new Date('2024-01-08'));
+});
+```
+
+## 6. UI Verification And Accessibility
+
+We avoid pixel-perfect visual regression tests by default. Screen structure and styles change often, and their maintenance cost is high. Instead, prioritize stable properties that users actually perceive and interact with.
+
+### What To Validate
+
+Write tests against attributes that are relatively stable from a user perspective, rather than against volatile implementation details.
+
+### Query Priority
+
+| Priority | Query | When To Use |
+| --- | --- | --- |
+| 1 | `getByRole` | Most semantic UI elements such as buttons, inputs, links, headings, and dialogs. Use with `name` whenever possible |
+| 2 | `getByLabelText` | Form fields connected to labels |
+| 3 | `getByDisplayValue` | When the current selected value is the best identifier |
+| 4 | `getByText` | When visible text is the most meaningful query |
+| 5 | `getByTestId` | Only when the other options are not practical |
+
+### `data-testid` Usage Standard
+
+Use `data-testid` only for elements that cannot be identified well through accessibility roles or similar user-facing semantics. Do not add `aria-label` only to make tests easier to query.
+
+```vue
+<button data-testid="submit-button">Submit</button>
+```
+
+```ts
+screen.getByTestId('submit-button'); // BAD
+screen.getByRole('button', { name: /submit/i }); // GOOD
+```
+
+```vue
+<div data-testid="product-card-skeleton">...</div>
+```
+
+```ts
+screen.getByTestId('product-card-skeleton');
+```
+
+For repeated UI, narrow by user-visible context with `within(...)` before falling back to `data-testid`.
+
+```ts
+const row = screen.getByRole('row', { name: /Samsung Electronics/i });
+expect(within(row).getByText('72,000')).toBeInTheDocument();
+```
+
+### Prefer To Avoid
+
+- CSS class names
+- DOM structure itself
+- Positional selectors such as `nth-child`
+- Auto-generated or meaningless `id` values
+- Text that is likely to change often
+- Broad snapshot comparisons
+
+## 7. Review Checklist
+
+Apply the [Review Checklist](common.md#review-checklist), and check:
+
+- Do the name and description accurately reflect what the test exercises and observes?

package/engineering/skills/test-review/templates/review.md

@@ -0,0 +1,21 @@
+# Test review: <Target>
+
+**Verdict:** <tests protect the change | gaps need attention | rework needed> — <One-sentence reason>
+
+## Missing protection
+- **P1 <Changed behavior>** — <Why no existing or new test would fail if it broke>; <smallest test that would cover it; omit this section when none>
+
+## Findings
+- **`<test file>`**
+  - **<P1 | P2 | P3> <Title>** (`<path:line>`) — <Issue and the failure scenario it allows>; <smallest fix; omit this section when none>
+
+---
+
+## Details
+Supporting context for reviewers; omit any subsection with nothing material to add.
+
+### Reviewed without findings
+- `<test file>` — <Behavior it protects>
+
+### Scope
+- <Guides applied, and any rule judged inapplicable with its reason>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/ghosts",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Reusable agent skills and reviewers.",
   "license": "MIT",
   "repository": {

package/engineering/skills/socratic-interview/SKILL.md

@@ -1,22 +0,0 @@
----
-name: socratic-interview
-description: Conduct a Socratic interview to resolve only material uncertainty, then provide a concise execution brief.
-disable-model-invocation: true
----
-
-Conduct a Socratic interview only when missing information could materially change the outcome, scope, behavior, safety, cost, or external action. Inspect context first and make normal in-scope assumptions when sufficient.
-
-Ask the smallest useful question, one at a time. Do not collect background that will not change the work. Stop when remaining uncertainty is immaterial; state assumptions and proceed unless doing so could cause an unwanted or costly result.
-
-Do not plan, implement, create tasks, write specs, or edit files during the interview.
-
-When sufficient, summarize only the decisions needed to execute:
-
-```md
-# Execution Brief
-
-- Outcome:
-- Decisions:
-- Scope and constraints:
-- Assumptions:
-```