olamedia/feature-architect

Feature Architect

CRITICAL: MUST NOT advance to the next step without explicit user permission. Complete the current step, present the result, and wait. When the user says nothing to add or nothing to fix — that IS permission to proceed. Do not ask again.

CRITICAL: During Step 1 (collecting intent), MUST NOT read any codebase files, scan directories, check project docs, or run research. The ONLY action allowed is writing the Intent block into requirements.md from the user's words. Research starts in Step 2, AFTER the user confirms the intent draft is complete.

CRITICAL: During Step 1, ALL user input is source material for the Intent block. References to folders, files, prior artifacts, context hints — everything goes into Intent. Record it, update requirements.md, and ask if there is more. Do not act on references until research starts.

CRITICAL: Each step has its own scope. Do NOT mix. Intent collects words. Research collects facts. Analytics loop resolves questions. Brief documents decisions. No analysis in intent, no design in research, no research in brief.

CRITICAL: MUST NOT speak questions to the user before they are written into requirements.md. Write first, present after. No exceptions.

CRITICAL: Any change mid-pipeline MUST propagate upstream-first. Go back to requirements.md, update intent/stories, then propagate to context-map.md. Never patch a downstream artifact without updating upstream. Describe impact, wait for agreement, apply in one batch.

Turn a raw idea (or YouTrack ticket, or testing report) into analysis artifacts: context-map.md, requirements.md, task-brief-{side}.md. The skill stops at the briefs — design, tasks, and implementation are downstream.

Detail sits in references/ (research.md, scan.md, splitting-checklist.md, brief-format.md, formats.md, issues-as-intent.md).

Apply human-techtalk subskill to all prose output.

When to Use

• A feature needs analysis before implementation — split identification, BE/FE scoping, question resolution
• The problem spans multiple areas and benefits from structured research before handing off to developer flows

Skip when: obvious single-file fix, only one step applies, or upstream artifacts already exist and you resume from the right step.

Input

• The idea, problem, or issue tracker task ID
• Artifact folder path — if none given, ask (e.g. docs/plans/feature-name/) and create it

Output

An artifact folder containing:

• workspace.md — repo index with paths to structure files (or scan notes)
• context-map.md — living document, updated throughout
• requirements.md — intent, goal, stories, questions log
• task-brief-{side}.md — one complete task brief per split part (e.g. task-brief-fe.md, task-brief-be.md; single task-brief.md for frontend-only)

Pipeline

Step 1: Collect Intent → Step 2: Initial Research → Step 3: Analytics Loop → Step 4: Brief
                                                ↑___________________|
                                                (return if gap found)

All research and open questions MUST be settled before the brief. If a gap is found during Step 4, return to Step 3 to resolve it, then resume.

Step 1: Collect Intent

No codebase reading. No research. Only write requirements.md.

1. If user provides a task ID: use issue tracker MCP (get_issue) if available. If MCP is not available, report it missing — user decides next step (paste text manually, provide URL, or skip).
2. If input is a testing report: normalize via issues-as-intent.md — classify rows, deduplicate, separate blockers from product goals.
3. If plain text: record the user's words verbatim into the Intent section.
4. User confirms intent is complete.

Gate: confirm, then proceed to research. Use structured questions.

Step 2: Initial Research

Mandatory first pass. Follow research.md (a standalone skill/reference) completely. Produces workspace.md and context-map.md. Later steps may invoke research.md again to fill gaps.

1. Build workspace.md: for each repo in the workspace, check for docs/TechStack.md, docs/ProjectStructure.md, docs/CodeStyle.md. Record paths found.
2. If any are missing: ask the user if they exist somewhere else. If no: run structured scan fallback (see scan.md), mark entry as scanned.
3. Save workspace.md.
4. Run FE research tracks: components, stores, composables, API client, routes, UI kit.
5. Run BE research track: map services from project docs, identify touched APIs. No BE source scanning.
6. Workspace detection: if the feature touches a repo not in the workspace, ask user for the path or suggest adding it. Update workspace.md.
7. Context classification: frontend-only / frontend+API / full-stack.
8. Verify coverage checklist (research.md).
9. Save context-map.md.

Gate: confirm, then proceed to analytics loop. Use structured questions.

Step 3: Analytics Loop

Starts with stories + goal. Loops through questions until all are resolved. Follow formats.md for artifact structure.

1. Prerequisite validation: coverage checklist passed, classification done, scope confirmed with user.
2. Extract initial user stories (US-xxx) + goal from intent + context map.
3. Questions loop:
   • Write [to-ask] questions into requirements.md before speaking them. When proposing answer choices, use structured questions.
   • Research when the codebase can answer a question — update context-map.md.
   • Record answers as [resolved] with rationale.
   • Update stories + goal after each answer.
   • Mark out-of-scope items [not-planned] with reason, deferred items [deferred] with reason.
4. Run splitting-checklist.md to identify split points (FE/BE/migration/cross-service).
5. Loop until no [to-ask] remain.
6. If a task ID was provided: anchor it in all artifact headers.
7. Save requirements.md.

Gate: confirm, then proceed to brief. Use structured questions.

Step 4: Brief

Produces one task-brief-{side}.md per split part. Follow brief-format.md completely.

1. Identify split parts from the splitting checklist results.
2. One complete task brief per split part — each is a self-contained document with Summary, User flow, Dependencies, Expected changes, API contract, Acceptance criteria, Out of scope, Notes, Testing notes.
3. Scope boundary: each brief targets exactly one side (FE or BE). FE briefs consume the BE contract as dependency, not define it.
4. Certainty rule: no uncertain language. Self-check after writing.
5. Data completeness: no placeholders. Unresolved details are explicit blockers.
6. Anti-fragmentation: each brief independently deployable. Merge non-deployable parts. Justify >3 briefs.
7. Frontend-only shortcut: if classification is frontend-only, single task-brief.md, skip split overhead.
8. Save task-brief-{side}.md files.

Gate: confirm via structured questions. List artifact folder contents. Skill is done — downstream flows take over.

Behavioral Baseline

Across all steps:

• Don't assume silently. State assumptions. Multiple interpretations → list them, don't pick.
• Nothing speculative. Minimum output that solves the ask. No extra features, unrequested flexibility.
• Surgical edits. Touch only what changed. Match existing style. Don't rewrite unaffected sections.
• Goal-driven. Tie work to verifiable criteria.

Structured Questions

When presenting choices to the user, use the IDE's structured question tool (AskQuestion in Cursor, or equivalent in other IDEs) if available. Applies to:

• Gates — "Continue to [next step]" / "Revise [current step]" / "Stop here"
• Question loop — proposed answers as selectable options + "Other (I'll type)" escape hatch
• Confirmations — "Complete, move on" / "I want to add more"
• Classification — scope level, priority, any pick-one/pick-many decision

Always include an open-ended escape option. Multi-select when the question genuinely allows it. Fall back to conversational text only if no structured question tool is available in the IDE.

Refuse

Refuse to: produce brief without written requirements, skip gates, accept "I know the repo" without an updated map, skip the first research pass, emit brief with unresolved questions.

Warning Signs

• Skipped or careless research
• Guessed APIs/components off the map
• Polished paraphrase instead of user's intent
• Proceeding while user is unsure
• Stale context-map.md
• Brief emitted with unresolved questions
• Mixing step scopes (analysis in intent, design in research)

Verification

• Artifacts exist in the folder
• workspace.md has an entry per repo in scope
• context-map.md matches research findings, append-only
• requirements.md holds intent in user's words, stories, and full questions log
• task-brief-{side}.md files exist per split part, no uncertain language, no placeholders
• Gates happened between all steps
• User has the folder path