| name | arch:generate-tactical-questions |
| description | Generates implementation-level questions about conventions and patterns already established in the codebase. Covers integration patterns, data schemas, API conventions, code conventions, testing strategy, and deployment. Every question includes a codebase_hint pointing scout to where the answer likely lives. Writes to $STORIES_DIR/{issueNumber}/tactical-questions.yaml (created if absent).
|
| argument-hint | [issue_number] |
| allowed-tools | ["Read","Glob","Grep","Bash","Write"] |
| write-paths | ["$AGENT_DOCS_DIR/"] |
arch:generate-tactical-questions
Surfaces the implementation-level unknowns before the architect maps acceptance criteria
to code. Every question here has a codebase_hint — a pointer that tells scout exactly
where in the codebase to look for the answer.
Workflow
Step 1 — Load context
STORY_FILE="${AGENT_DOCS_DIR:-docs}/active-story.yaml"
if [ ! -f "$STORY_FILE" ]; then
echo "ERROR No active story. Run /github:story-fetch first."
exit 1
fi
ISSUE_NUMBER=$(grep 'issueNumber:' "$STORY_FILE" | awk '{print $2}')
STORIES_DIR="${STORIES_DIR:-agent-docs/stories}"
OUTPUT_DIR="${STORIES_DIR}/${ISSUE_NUMBER}"
OUTPUT_PATH="${OUTPUT_DIR}/tactical-questions.yaml"
STRATEGIC_PATH="${OUTPUT_DIR}/strategic-questions.yaml"
mkdir -p "$OUTPUT_DIR"
Read:
$AGENT_DOCS_DIR/active-story.yaml — story title, issueNumber, ACs, NFRs$STORIES_DIR/{issueNumber}/strategic-questions.yaml — avoid duplicating strategic answers$ADR_DIR — skip questions already decided in ADRs
Step 2 — Analyse story scope
For each AC, identify which tactical domains are touched:
| AC involves… | Category to generate questions for |
|---|
| Calling or exposing an API / event / message | integration_patterns |
| Reading or writing persistent data | data_schemas |
| Exposing a new HTTP endpoint | api_conventions |
| Adding new source files or business logic | code_conventions |
| Requiring test coverage | testing |
| Shipping to an environment | deployment |
Skip any category not touched by any AC.
Step 3 — Generate questions
For each relevant category, generate targeted questions from the catalogue below.
Skip questions whose answers are already in ADRs or strategic-questions.yaml.
Add codebase_hint to every question — tell scout where to look.
Category: integration_patterns
- Is synchronous (REST/GraphQL) or asynchronous (event/queue) integration preferred here?
- hint: look for existing event publishers or SQS/SNS producers in the codebase
- What event schema format is used (JSON Schema, Avro, Protobuf)?
- hint: look for schema files or event type definitions
- What is the retry and dead-letter queue policy for async consumers?
- hint: look for existing consumer Lambda or ECS handler configurations
- Is idempotency enforced? What mechanism is used?
- hint: look for idempotency keys or deduplication logic in existing handlers
- Are there circuit breaker or timeout standards for outbound calls?
- hint: look for HTTP client wrappers or middleware
Category: data_schemas
- What schema migration toolchain is in use (Flyway, Liquibase, Prisma, TypeORM)?
- hint: look for migration files or ORM configuration
- What is the naming convention for tables, columns, and indexes?
- hint: look at existing migration files or entity definitions
- Is soft-delete (
deletedAt) or hard-delete the convention?
- hint: look for existing entity base classes or repository patterns
- Is there a schema registry for event schemas?
- hint: look for schema registry config or EventBridge schema references
- What is the convention for audit fields (createdAt, updatedAt, createdBy)?
- hint: look for base entity or abstract model classes
Category: api_conventions
- What versioning strategy is used for HTTP APIs (URL path, header)?
- hint: look at existing route definitions or API Gateway config
- What authentication mechanism is expected on new endpoints (JWT, API key, Cognito)?
- hint: look for auth middleware or Lambda authoriser definitions
- What is the standard error response envelope format?
- hint: look for error handler middleware or existing 4xx/5xx responses
- What pagination style is used (cursor, offset, page)?
- hint: look for existing list/query endpoints
- Is there a rate limiting or throttling policy to inherit?
- hint: look for API Gateway usage plan or middleware config
Category: code_conventions
- What dependency injection pattern or container is in use?
- hint: look for DI config files or container setup (tsyringe, InversifyJS, NestJS)
- What is the error handling standard (Result type, exceptions, error codes)?
- hint: look for error base classes or service-level try/catch patterns
- What logging library and format is expected (structured JSON, correlation IDs)?
- hint: look for logger instantiation in existing services
- Is there a domain model or DTO separation pattern to follow?
- hint: look for dto/, domain/, or model/ directories
- What linting / formatting rules are enforced?
- hint: look for .eslintrc, .prettierrc, or similar config files
Category: testing
- What is the minimum unit test coverage threshold?
- hint: look for jest.config.ts coverageThreshold or similar
- What is the strategy for test data — factories, fixtures, or seeds?
- hint: look for test/fixtures/, test/factories/, or seeder files
- Are mocks preferred over integration tests for external services?
- hint: look for existing
__mocks__ directories or nock/msw setups
- What is the integration test strategy — real DB or in-memory?
- hint: look for test database config or testcontainers usage
- Are contract tests required for new API endpoints?
- hint: look for Pact or OpenAPI contract test files
Category: deployment
- What are the required CI/CD pipeline stages before production?
- hint: look for .github/workflows/ or buildspec.yml
- What is the environment promotion strategy (dev → staging → prod)?
- hint: look for environment-specific config or deploy scripts
- Is a feature flag required to gate this feature in production?
- hint: look for feature flag service config (LaunchDarkly, AWS AppConfig)
- Is blue/green or canary deployment required for this change?
- hint: look for CodeDeploy config or ECS deployment config
- Are there post-deployment smoke tests or health check gates?
- hint: look for post-deploy test scripts or deployment hooks
Step 4 — Deduplicate
Before writing, check each question:
grep -r "QUESTION_TOPIC" "${ADR_DIR:-docs/adr}" 2>/dev/null
grep "QUESTION_TOPIC" "${STRATEGIC_PATH}" 2>/dev/null
If already answered, set answer: to the reference rather than null.
Step 5 — Write output
Write $STORIES_DIR/{issueNumber}/tactical-questions.yaml:
generated_at: "YYYY-MM-DD"
story: "{issueNumber} — {title}"
questions:
- id: TQ-001
category: integration_patterns
question: "Is synchronous or asynchronous integration preferred for the order event?"
context: "AC-2 requires publishing an order-placed event"
codebase_hint: "Look for existing event publishers under src/events/ or src/messaging/"
answer: null
- id: TQ-002
category: data_schemas
question: "What is the soft-delete convention for order records?"
context: "AC-4 requires order cancellation without data loss"
codebase_hint: "Look for deletedAt fields or BaseEntity class in src/entities/"
answer: null
IDs are sequential: TQ-001, TQ-002, …
If the file already exists, merge: preserve existing answer: values, append new questions.
Step 6 — Report
arch:generate-tactical-questions: {N} questions written
integration_patterns {n} questions
data_schemas {n} questions
api_conventions {n} questions
code_conventions {n} questions
testing {n} questions
deployment {n} questions
{m} already answered (from ADRs / strategic-questions.yaml)
Output: $STORIES_DIR/{issueNumber}/tactical-questions.yaml
Next: send scout to answer both strategic and tactical question files.
Output
| File | Content |
|---|
$STORIES_DIR/{issueNumber}/tactical-questions.yaml | Structured question list with codebase_hint on every question |
Error Handling
| Condition | Behaviour |
|---|
| No active story | Error: run /github:story-fetch first |
| No ACs in story | Warn and generate only code_conventions + deployment questions |
| File already exists | Merge: preserve answers, append new questions |
