, `^\\s*\u003c!--`, or `^\\s*#`.\n\nIf the file exists with real content, present these options — the skill does NOT silently overwrite or merge with existing content:\n\n1. **Delete and start fresh** — \"Delete the existing doc and start fresh with reverse-engineer mode.\" Destructive but clean.\n2. **Keep existing** — \"Keep the existing doc — use `/cupdate-arch` for feature-level updates instead.\" Redirects to the right tool.\n3. **Exit** — \"Exit — I'll handle this manually.\"\n\nDo not proceed to mode selection until the user chooses. If the user picks option 2, print the redirect message and stop. If option 3, stop.\n\n### Mode Selection (R-009)\n\nIf no `--greenfield` or `--reverse-engineer` flag was provided and the existing-content check did not trigger, ask:\n\n\u003e Does this project have meaningful existing code I should analyze, or are we designing from scratch?\n\u003e\n\u003e 1. **Reverse-engineer** — analyze existing code\n\u003e 2. **Greenfield** — design from scratch\n\n---\n\n## Greenfield Mode (R-003)\n\n### Discovery Questions\n\nAsk concrete discovery questions tied to the user's project. Do not generate generic questions — adapt to their answers iteratively.\n\nMandatory first-round questions:\n1. What does this system do? (1-2 sentences)\n2. Who or what calls it? (users, other services, cron, CLI)\n3. What does it call? (databases, APIs, message queues, file systems)\n4. How is it deployed? (container, serverless, bare metal, library)\n5. What is the primary optimization priority? (latency, throughput, correctness, developer velocity)\n6. What constraints exist? (compliance, SLAs, language restrictions, team size)\n\nFollow-up questions are driven by the answers — do not repeat questions whose answers are already known.\n\n### Architectural Decisions — Tiered Format (R-008)\n\nPresent architectural decisions using this tiered format:\n\n**Tier 1** (fundamental, hard-to-reverse decisions) — full tradeoffs:\n- Numbered options (minimum 2)\n- Each option includes:\n - Advantages\n - Disadvantages\n - **Best when**: qualifier describing the ideal use case for this option\n- A recommendation with rationale\n- An escape hatch: \"Or describe your own approach: ___\"\n\n**Tier 2** (significant but reversible decisions) — brief tradeoffs + recommendation:\n- Numbered options with 1-2 sentence tradeoff each\n- Recommendation with brief rationale\n\n**Tier 3** (minor, easily changed decisions) — recommendation only:\n- Recommendation with brief rationale\n- No options listed unless the user asks\n\n### Output\n\nDo not produce scaffolding or code. Document only. Write the output to `.correctless/ARCHITECTURE.md` following the section structure defined below.\n\n---\n\n## Reverse-Engineer Mode (R-002)\n\n### Codebase Scan\n\nScan the codebase for structural patterns. Respect `.gitignore` and exclude known vendor/dependency directories: `node_modules/`, `vendor/`, `.venv/`, `target/`, `build/`, `dist/`.\n\n### Coverage Report (R-010)\n\nBefore presenting the draft, output a structured coverage report:\n\n1. **Directories scanned** with file counts per directory\n2. **Files analyzed vs skipped** with skip reasons:\n - Too small (\u003c 5 lines)\n - Binary files\n - Generated files (auto-generated headers, lockfiles)\n - Vendored/dependency directories\n3. **Patterns detected** with file lists per pattern group\n\nThe user sees the sampling, not just the conclusions. This transparency is mandatory.\n\n### Inconsistency Handling\n\nWhen you detect inconsistent patterns in the codebase, present them as enumerated groups:\n\n\u003e \"X handlers do A, Y handlers do B — which is canonical?\"\n\nDo not silently pick the majority pattern. Present the conflict and require user confirmation before documenting either pattern as canonical.\n\n### Pattern Batching (R-013)\n\nDetected patterns are batched by confidence:\n\n**High-confidence patterns** (\u003e= 75% of examined files of that type following the pattern):\n- Present as a group with a \"confirm all or drill into any\" prompt.\n- \"Files of that type\" means files matching the pattern being documented — e.g., for a \"handler pattern,\" files in the handler directory or files matching a skill-determined glob.\n\n**Low-confidence patterns** (\u003c 75%):\n- Present individually with 2-3 representative files.\n- Ask: \"Is this pattern intentional, or is this coincidence?\"\n\nPatterns the user rejects are not documented. Patterns confirmed are documented with representative files as examples.\n\n**Cap**: At most 10 patterns per session. If more are detected, rank by coverage percentage and defer the rest with: \"N additional patterns detected — run `/carchitect --continue` to review the next batch.\" (See `--continue` flag description above for session-scope limitation.)\n\n### User Confirmation\n\nRequire user confirmation before writing any pattern as canonical. Never commit a pattern to the document without explicit approval.\n\n### Adversarial Second Pass (R-006)\n\nAfter drafting the `.correctless/ARCHITECTURE.md`, invoke the adversarial second-pass agent:\n\n```\nTask(subagent_type=\"correctless:architecture-reviewer\")\n```\n\nPass it the draft `.correctless/ARCHITECTURE.md` path and the project root. The agent reads the draft and the codebase with the prompt: \"Find patterns this document claims exist but that the codebase violates. Find entrypoints the document misses.\"\n\nFindings are categorized as:\n- **(a)** Pattern claimed but violated — the doc says X, but files Y and Z do the opposite\n- **(b)** Entrypoint missing — the doc does not list entrypoint Z, but it exists\n- **(c)** Inconsistency smoothed over — the draft picked a side without flagging the conflict\n\nPresent findings to the user sequentially, one at a time, consistent with the `/creview` presentation pattern. The user adjudicates each finding before seeing the next.\n\n---\n\n## Output: .correctless/ARCHITECTURE.md Section Structure (R-007)\n\nThe output `.correctless/ARCHITECTURE.md` contains these sections in this order:\n\n1. **System Purpose and Boundaries** — what the system does, what it does not do, external dependencies\n2. **Entrypoints** — structured YAML block (see below) + prose description of each\n3. **Key Patterns** — recurring structural patterns in the codebase\n4. **Layer Conventions** — how the codebase is organized (layers, modules, packages)\n5. **Anti-Patterns** — known violations, tech debt, things to avoid\n6. **Decision Log** — architectural decisions made during this session\n7. **Known Limitations** — scope gaps, deferred concerns, areas of uncertainty\n\nOf these, only **Entrypoints** is mandatory and structured (YAML block). The remaining sections are prose stubs that the user can fill in. Populate what you can from discovery/analysis, but mark uncertain sections with `\u003c!-- TODO: verify --\u003e` rather than presenting guesses as facts.\n\n---\n\n## Entrypoints YAML Schema (R-004, R-014)\n\nThe `## Entrypoints` section contains a fenced YAML block between marker comments:\n\n```markdown\n\u003c!-- correctless:entrypoints:start --\u003e\n```yaml\n- name: \"api-server\"\n type: http\n handler: \"cmd/server/main.go:main\"\n test_via: \"httptest.NewServer(handler)\"\n scope:\n - \"pkg/api/**\"\n - \"pkg/middleware/**\"\n```\n\u003c!-- correctless:entrypoints:end --\u003e\n```\n\n### Field Definitions\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | yes | Human-readable entrypoint name |\n| `type` | enum | yes | One of: `http`, `cli`, `grpc`, `queue`, `cron`, `library`, `websocket` |\n| `handler` | string | yes | File path + symbol (e.g., `cmd/server/main.go:main`) |\n| `test_via` | string (non-empty) | yes | How an integration test reaches this entrypoint. For HTTP: test server construction. For CLI: exec invocation. For library: public API import. Must not be empty. |\n| `scope` | list of strings | yes | Glob patterns for source files this entrypoint governs |\n\n### Write-Time Validation (R-004)\n\nBefore writing the entrypoints YAML to disk, validate all fields:\n\n1. Every entry has all required fields (`name`, `type`, `handler`, `test_via`, `scope`).\n2. `type` is one of the allowed enum values: `http`, `cli`, `grpc`, `queue`, `cron`, `library`, `websocket`.\n3. `test_via` is a non-empty string.\n4. `scope` is a non-empty list.\n\n**Invalid entries are rejected with an error message, not written.** Do not silently drop or fix invalid entries — report the specific validation failure to the user and ask them to correct it.\n\n---\n\n## MCP Integration (optional)\n\nCheck `.correctless/config/workflow-config.json` for MCP availability:\n\n| MCP Tool | When Available | Fallback |\n|----------|----------------|----------|\n| Serena `get_symbols` | Symbol-level code analysis for entrypoint discovery | Grep for function/class definitions |\n| Serena `find_references` | Cross-reference tracing for scope mapping | Grep for import/require statements |\n| Serena `get_file_symbols` | File-level symbol enumeration | Read + manual parsing |\n| Context7 `resolve-library-id` | Library convention lookup | Skip — use codebase patterns only |\n| Context7 `query-docs` | Framework-specific pattern verification | Skip — use codebase patterns only |\n\nSerena and Context7 are optimizers, not dependencies. If unavailable, fall back silently — no abort, no retry, no mid-operation warnings. Notify once at the end of the session if MCP was unavailable.\n\n---\n\n## Autonomous Defaults\n\nWhen running in autonomous mode (`mode: autonomous` in prompt context), use these defaults instead of pausing for human input.\nWhen dispatched by `/cauto`, return autonomous decisions in the `AUTONOMOUS_DECISIONS_START`/`AUTONOMOUS_DECISIONS_END` format provided in the task prompt.\n\n- **AD-001**: New component discovery — auto-add all discovered components (default). Rationale: components are derived from codebase structure and are factual, not subjective.\n- **AD-002**: Pattern classification — apply closest matching existing pattern (default). Rationale: pattern matching against existing PAT-xxx entries is mechanical and low-risk.\n- **AD-003**: Architecture entry approval — `escalate: always`. Default if deferred: skip — flag for human review. Rationale: new ABS/PAT/TB entries are architectural decisions that shape all future features.\n\n## Phase 0 Scope Constraints (R-012)\n\nThis is Phase 0. The following constraints are non-negotiable:\n\n- **Standalone**: Do not modify any other skill's SKILL.md, frontmatter, or behavior.\n- **Write target**: Only `.correctless/ARCHITECTURE.md`. No other files.\n- **No enforcement**: The document is advisory in Phase 0.\n- **No scaffolding**: Document only — no code generation.\n- **No maintenance**: `/cupdate-arch` handles feature-level deltas.\n","repo_fullName":"joshft/correctless","repo_stars":61,"repo_language":"Shell","repo_license":"MIT","repo_pushedAt":"2026-05-31T04:51:30Z","owner_login":"joshft","owner_type":"User","owner_name":"josh","owner_avatarUrl":"https://avatars.githubusercontent.com/u/2847920?v=4"}};