ariadna 1.1.3 → 1.2.0

data/data/ariadna/templates/research-project/PITFALLS.md

@@ -155,7 +155,7 @@ params.require(:user).permit(:name, :email)
 [Root cause — e.g., tenant scoping not enforced at the framework level, new developers unaware of scoping requirements, background jobs not carrying tenant context]
 
 **How to avoid:**
-[Prevention strategy — e.g., acts_as_tenant gem, Current attributes for tenant context, controller-level `around_action` for scoping, test isolation per tenant]
+[Prevention strategy — e.g., Current attributes for tenant context, controller-level `around_action` for scoping, test isolation per tenant]
 
 **Warning signs:**
 [How to detect early — e.g., queries without `WHERE tenant_id = ?`, cross-tenant data appearing in tests, background jobs processing wrong tenant data]
@@ -184,6 +184,53 @@ params.require(:user).permit(:name, :email)
 
 ---
 
+### Pitfall 7: Explicit Translation Keys Instead of ActiveRecord Automatic Lookup
+
+**What goes wrong:**
+[Describe where explicit `t()` calls duplicate what Rails I18n automatic lookup provides — e.g., form labels passing explicit keys, validation messages hardcoded, model names translated manually]
+
+**Why it happens:**
+[Root cause — e.g., developers unaware of ActiveRecord I18n conventions, copying patterns from non-Rails projects, not reading Rails I18n guide]
+
+**How to avoid:**
+[Prevention strategy — e.g., use `form.label :name` instead of `form.label :name, t("teams.form.name")`, define translations under `activerecord.attributes.*` and `activerecord.models.*`, rely on automatic lookup for validation messages]
+
+**Warning signs:**
+[How to detect early — e.g., duplicate translation keys for the same attribute in different namespaces, inconsistent labels between forms and error messages, `t()` calls in form labels that mirror `activerecord.attributes` keys]
+
+**Example:**
+```ruby
+# Bad — explicit key duplicates what Rails provides automatically
+<%= form.label :name, t("teams.form.name") %>
+# Requires: teams.form.name in locale file AND activerecord.attributes.team.name for validations
+
+# Good — resolves from activerecord.attributes.team.name automatically
+<%= form.label :name %>
+# Single source of truth: activerecord.attributes.team.name used by forms AND validations
+```
+
+```yaml
+# Good — single source of truth for attribute names
+en:
+  activerecord:
+    models:
+      team: "Team"
+    attributes:
+      team:
+        name: "Team name"
+    errors:
+      models:
+        team:
+          attributes:
+            name:
+              blank: "cannot be empty"
+```
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
 [Continue for additional critical pitfalls specific to this application...]
 
 ## Technical Debt Patterns
@@ -215,6 +262,7 @@ Common mistakes when integrating Rails gems and external services.
 | Turbo / Hotwire | [e.g., full page reloads from misconfigured frames, missing turbo stream responses, form submission edge cases] | [what to do instead] |
 | Rails version upgrades | [e.g., skipping deprecation warnings, upgrading multiple major versions at once, not running `rails app:update`] | [what to do instead] |
 | Third-party APIs | [e.g., no circuit breaker, synchronous calls in request cycle, no webhook signature verification] | [what to do instead] |
+| I18n / rails-i18n | [e.g., using explicit `t()` keys for model attributes and form labels instead of ActiveRecord automatic lookup, missing `rails-i18n` gem for CLDR data (dates, currency, numbers), inconsistent locale file organization mixing per-model and flat structures] | [e.g., define translations under `activerecord.attributes.*` and `activerecord.models.*`, use `form.label :field` without explicit `t()`, add `rails-i18n` gem for base locale data, organize locale files consistently] |
 | [integration] | [what people do wrong] | [what to do instead] |
 
 ## Performance Traps
@@ -241,7 +289,7 @@ Rails-specific security issues beyond basic web security.
 | SQL injection via string interpolation in `where` | [e.g., user input directly in query string allows data exfiltration] | [e.g., always use parameterized queries: `where("name = ?", params[:name])` or hash syntax `where(name: params[:name])`] |
 | CSRF token handling gaps | [e.g., API endpoints without `protect_from_forgery`, token not verified on state-changing requests] | [e.g., `protect_from_forgery with: :exception`, proper token handling for JS requests, `csrf_meta_tags` in layout] |
 | Credential management mistakes | [e.g., secrets in ENV vars without encryption, credentials checked into git, different credentials per environment not managed] | [e.g., Rails encrypted credentials, `rails credentials:edit`, per-environment credential files] |
-| Insecure direct object references | [e.g., `User.find(params[:id])` without authorization check, enumerable IDs exposing records] | [e.g., always scope to authorized records: `current_user.posts.find(params[:id])`, use Pundit/CanCanCan] |
+| Insecure direct object references | [e.g., `User.find(params[:id])` without authorization check, enumerable IDs exposing records] | [e.g., always scope to authorized records: `current_user.posts.find(params[:id])`, use Current.account or Current.employee] |
 | Mass assignment vulnerabilities | [e.g., unpermitted nested attributes modifying admin fields, `accepts_nested_attributes_for` without `reject_if`] | [e.g., explicit strong parameters, test that admin attributes cannot be set via API, `attr_readonly` for sensitive fields] |
 | Unsafe `html_safe` / `raw` usage | [e.g., XSS from marking user input as safe, rendering unescaped HTML from database] | [e.g., never call `html_safe` on user input, use `sanitize` helper, Content Security Policy headers] |
 | Open redirects | [e.g., `redirect_to params[:return_to]` allows redirecting to malicious sites] | [e.g., validate redirect URLs against allowlist, use `redirect_back` with `fallback_location`] |
@@ -261,6 +309,7 @@ Rails features that appear complete but are missing critical pieces.
 - [ ] **Database connection pooling:** Pool size matches worker/thread count — verify `database.yml` pool matches Puma thread count
 - [ ] **Timezone handling:** Application uses `Time.current` / `Date.current` instead of `Time.now` / `Date.today` — verify `config.time_zone` is set and used consistently
 - [ ] **Email delivery:** Mailers use `deliver_later` not `deliver_now` in web requests — verify mailer calls don't block request cycle
+- [ ] **I18n locale completeness:** All supported locales have matching keys for `activerecord.models.*`, `activerecord.attributes.*`, and `activerecord.errors.*` — verify with `i18n-tasks` gem or manual comparison that no locale is missing translations present in others
 - [ ] **[Feature]:** Often missing [thing] — verify [check]
 - [ ] **[Feature]:** Often missing [thing] — verify [check]
 

data/data/ariadna/templates/research-project/STACK.md

@@ -52,13 +52,14 @@ Template for `.planning/research/STACK.md` — discovered technology stack for t
 | File storage service | [local/S3/GCS/Azure/none] | [config/storage.yml] |
 | Email | [Action Mailer/Postmark/SendGrid/none] | [Gemfile, mailer configs] |
 | PDF generation | [Prawn/wicked_pdf/Grover/none] | [Gemfile] |
+| Internationalization | [rails-i18n gem / manual locale files only / none] | [Gemfile, config/locales/] |
 
 ## Authentication & Authorization
 
 | Category | Discovered Value | Evidence |
 |----------|-----------------|----------|
 | Authentication | [Rails authentication generator/Rodauth/Clearance/custom/none] | [Gemfile, user model] |
-| Authorization | [Pundit/CanCanCan/Action Policy/custom/none] | [Gemfile, policy files] |
+| Authorization | [Custom/Pundit/CanCanCan/Action Policy/none] | [Gemfile, policy files] |
 | OAuth/social login | [OmniAuth/Doorkeeper/none] | [Gemfile, initializers] |
 | API authentication | [API tokens/JWT/OAuth2/none] | [Gemfile, controller concerns] |
 
@@ -209,38 +210,38 @@ bin/rails server
 - Look at `database.yml` for multiple database configurations
 
 **Frontend & Assets:**
-- Check for `config/importmap.rb` (Importmap), `package.json` (Node-based), or `vite.config.ts` (Vite)
-- Look at `app/views/layouts/application.html.erb` for asset tags
-- Check `app/javascript/` structure and `app/assets/` for CSS approach
-- Look for `app/components/` (ViewComponent) or Phlex usage
+- Check for `config/importmap.rb` (Importmap), `package.json` (Node-based), or `vite.config.ts` (Vite).
+- Look at `app/views/layouts/application.html.erb` for asset tags.
+- Check `app/javascript/` structure and `app/assets/` for CSS approach.
+- Look for `app/components/` (ViewComponent) or Phlex usage.
 
 **Backend Services:**
-- Check `config/application.rb` for `active_job.queue_adapter` setting
-- Check `config/environments/production.rb` for cache store configuration
-- Look at `config/cable.yml` for Action Cable adapter
-- Check `config/storage.yml` for Active Storage service
+- Check `config/application.rb` for `active_job.queue_adapter` setting.
+- Check `config/environments/production.rb` for cache store configuration.
+- Look at `config/cable.yml` for Action Cable adapter.
+- Check `config/storage.yml` for Active Storage service.
 
 **Authentication & Authorization:**
-- Look for `Authentication` concern generated by `rails generate authentication`
-- Look for `app/policies/` (Pundit) or `app/models/ability.rb` (CanCanCan)
-- Check `app/models/user.rb` for authentication modules
+- Look for `Authentication` concern generated by `rails generate authentication`.
+- Look for `app/policies/` (Pundit) or `app/models/ability.rb` (CanCanCan) or custom authorization logic.
+- Check `app/models/user.rb` for authentication modules.
 
 **Testing:**
 - Determine framework: check for `test/` (Minitest, recommended) vs `spec/` (RSpec)
-- Check `test/test_helper.rb` (Minitest) or `spec/rails_helper.rb` (if RSpec) for test configuration
-- Look for `test/fixtures/` or `spec/factories/` to determine data strategy
-- Check for system test configuration and browser driver
+- Check `test/test_helper.rb` (Minitest) or `spec/rails_helper.rb` (if RSpec) for test configuration.
+- Look for `test/fixtures/` or `spec/factories/` to determine data strategy.
+- Check for system test configuration and browser driver.
 
 **What to Avoid:**
-- Flag gems that are no longer maintained or have known security issues
-- Note deprecated Rails patterns found in the codebase (e.g., `before_filter`, `attr_accessible`)
-- Identify gems that duplicate Rails built-in functionality unnecessarily
-- Flag any gems with known incompatibilities with the discovered Rails version
+- Flag gems that are no longer maintained or have known security issues.
+- Note deprecated Rails patterns found in the codebase (e.g., `before_filter`, `attr_accessible`).
+- Identify gems that duplicate Rails built-in functionality unnecessarily.
+- Flag any gems with known incompatibilities with the discovered Rails version.
 
 **Gem Inventory:**
-- Record version constraints as written in the Gemfile, not resolved versions
-- Note which Bundler group each gem belongs to
-- For important gems, check if the version is current or significantly outdated
+- Record version constraints as written in the Gemfile, not resolved versions.
+- Note which Bundler group each gem belongs to.
+- For important gems, check if the version is current or significantly outdated.
 
 **Version Compatibility:**
 - Note any gems that pin to specific Rails or Ruby versions

data/data/ariadna/templates/research-project/SUMMARY.md

@@ -53,7 +53,7 @@ Template for `.planning/research/SUMMARY.md` — executive summary of project re
 
 **Authentication & authorization:**
 - [Auth solution]: [purpose] — [why recommended — e.g., Rails authentication generator for session-based auth]
-- [Authorization]: [purpose] — [why recommended — e.g., Pundit for policies, Action Policy for scalable rules]
+- [Authorization]: [purpose] — [why recommended — e.g., before_action, Pundit for policies, Action Policy for scalable rules]
 
 **Additional gems:**
 - [Gem]: [purpose] — [why recommended]
@@ -87,7 +87,7 @@ Template for `.planning/research/SUMMARY.md` — executive summary of project re
 6. [Data access patterns] — [approach — e.g., scopes, query objects, eager loading strategy]
 
 **Multi-tenancy approach (if applicable):**
-- [Strategy] — [e.g., acts_as_tenant scoping, PostgreSQL schemas, separate databases]
+- [Strategy] — [e.g., Denormalise tables with account_id and use Current.account, PostgreSQL schemas, separate databases]
 
 **Engine extraction (if applicable):**
 - [Engine/mountable concern] — [e.g., admin engine, API engine, shared authentication engine]

data/data/ariadna/workflows/new-project.md

@@ -14,9 +14,9 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config questions still required (Step 5)
+- Skip config questions — use opinionated defaults (Step 5)
 - After config: run Steps 6-9 automatically with smart defaults:
-  - Research: Always yes
+  - Research: No (Rails conventions pre-loaded). Use `--auto --research` to force research.
   - Requirements: Include all table stakes + features from provided document
   - Requirements approval: Auto-approve
   - Roadmap approval: Auto-approve
@@ -215,129 +215,45 @@ mkdir -p .planning
 ariadna-tools commit "docs: initialize project" --files .planning/PROJECT.md
 ```
 
-## 5. Workflow Preferences
+## 5. Workflow Configuration
 
-**Round 1 — Core workflow settings (4 questions):**
+**Use opinionated defaults. Only ask if user wants to customize.**
 
-```
-questions: [
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Depth",
-    question: "How thorough should planning be?",
-    multiSelect: false,
-    options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Execution",
-    question: "Run plans in parallel?",
-    multiSelect: false,
-    options: [
-      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
-      { label: "Sequential", description: "One plan at a time" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
-    ]
+Apply these defaults directly to `.planning/config.json`:
+
+```json
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": false,
+    "plan_check": true,
+    "verifier": true
   }
-]
+}
 ```
 
-**Round 2 — Workflow agents:**
-
-These spawn additional agents during planning/execution. They add tokens and time but improve quality.
-
-| Agent | When it runs | What it does |
-|-------|--------------|--------------|
-| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
-| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
-| **Verifier** | After phase execution | Confirms must-haves were delivered |
-
-All recommended for important projects. Skip for quick experiments.
+**Ask ONE question — only the non-obvious setting:**
 
 ```
 questions: [
   {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "Model Profile",
-    question: "Which AI models for planning agents?",
+    header: "Depth",
+    question: "How thorough should planning be?",
     multiSelect: false,
     options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+      { label: "Standard (Recommended)", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
+      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
     ]
   }
 ]
 ```
 
-Create `.planning/config.json` with all settings:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
-  "parallelization": true|false,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false
-  }
-}
-```
-
-**If commit_docs = No:**
-- Set `commit_docs: false` in config.json
-- Add `.planning/` to `.gitignore` (create if needed)
-
-**If commit_docs = Yes:**
-- No additional gitignore entries needed
+Create `.planning/config.json` with the defaults above, applying the user's depth selection.
 
 **Commit config.json:**
 
@@ -345,24 +261,26 @@ Create `.planning/config.json` with all settings:
 ariadna-tools commit "chore: add project config" --files .planning/config.json
 ```
 
-**Note:** Run `/ariadna:settings` anytime to update these preferences.
+**Note:** Run `/ariadna:settings` anytime to update these preferences (research, model profile, parallelization, etc.).
 
 ## 5.5. Resolve Model Profile
 
-Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
+Use models from init: `roadmapper_model`.
 
 ## 6. Research Decision
 
-**If auto mode:** Default to "Research first" without asking.
+**Default: Skip research.** Rails conventions are pre-loaded via `rails-conventions.md` reference document, which provides standard stack, architecture patterns, common pitfalls, and testing patterns.
 
-Use AskUserQuestion:
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
+**If `--research` flag was passed or auto mode:** Run full research (see below).
 
-**If "Research first":**
+**Otherwise:** Display skip notice and continue to Step 7:
+
+```
+Using pre-loaded Rails conventions (stack, architecture, patterns, pitfalls).
+To research instead: /ariadna:new-project --research
+```
+
+**If research requested (`--research` flag or auto mode):**
 
 Display stage banner:
 ```
@@ -596,7 +514,7 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
-**If "Skip research":** Continue to Step 7.
+**If research not requested:** Continue to Step 7.
 
 ## 7. Define Requirements
 
@@ -769,6 +687,9 @@ Task(prompt="
 **Research (if exists):**
 @.planning/research/SUMMARY.md
 
+**Rails Conventions (pre-loaded domain knowledge):**
+@~/.claude/ariadna/references/rails-conventions.md
+
 **Config:**
 @.planning/config.json
 
@@ -780,8 +701,9 @@ Create roadmap:
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
 4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-6. Return ROADMAP CREATED with summary
+5. Use Rails conventions reference for standard patterns and build order
+6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+7. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
@@ -903,14 +825,15 @@ Present completion with next steps:
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/ariadna:discuss-phase 1 — gather context and clarify approach
+/ariadna:plan-phase 1
 
 <sub>/clear first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- /ariadna:plan-phase 1 — skip discussion, plan directly
+- /ariadna:discuss-phase 1 — gather detailed context before planning (optional)
+- /ariadna:plan-phase 1 --research — research before planning (for non-standard integrations)
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -940,18 +863,18 @@ Present completion with next steps:
 - [ ] Brownfield detection completed
 - [ ] Deep questioning completed (threads followed, not rushed)
 - [ ] PROJECT.md captures full context → **committed**
-- [ ] config.json has workflow mode, depth, parallelization → **committed**
-- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
-- [ ] Requirements gathered (from research or conversation)
+- [ ] config.json has opinionated defaults → **committed**
+- [ ] Research completed (only if `--research` flag) — 4 parallel agents spawned → **committed**
+- [ ] Requirements gathered (from research or conversation, with Rails conventions as context)
 - [ ] User scoped each category (v1/v2/out of scope)
 - [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
-- [ ] ariadna-roadmapper spawned with context
+- [ ] ariadna-roadmapper spawned with context (including rails-conventions.md)
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] User knows next step is `/ariadna:discuss-phase 1`
+- [ ] User knows next step is `/ariadna:plan-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.