Requirement Types

Every requirement in Forgexa has a type that determines how AI agents analyze it, what documents are produced, which execution phases run, and how the quality gate is scored. Choosing the right type ensures the pipeline is efficient and the outputs are appropriate.

Overview

Type	Label	Best for	AI Phases	Analysis Docs
feature	Feature	New user-facing functionality	4	5
bugfix	Bug Fix	Reproducing and fixing known bugs	4	4
refactor	Refactor	Restructuring code without behavior change	3	3
documentation	Documentation	Writing or updating docs	2	2
improvement	Improvement	Iterating on existing features	4	4
task	Task	Engineering tasks, scripts, configs	1–2	2
spike	Research	Technical research and PoC	2–3	2
faq	FAQ	Answering technical questions	2	2

Aliases: bug → bugfix, story → feature, support → faq. These aliases can be used when creating work items on the Board.

Type Reference

Feature

Use when you are building new user-facing functionality from scratch — a new API endpoint, a new UI screen, a new integration, etc.

Analysis produces:

Document	What it contains
Product Requirements Doc (PRD)	User stories, acceptance criteria, edge cases, non-functional requirements
Technical Design Doc (SDD)	Architecture decisions, API contracts, data model changes
Task Breakdown (TASKS)	Subtasks and dependencies for the execution pipeline
Test Scenarios Plan	A structured list of test cases the AI must cover

Execution phases: Design → Implement → Test → Review

Gate Score focus: All six dimensions are scored with balanced weights. Test coverage (20%), code quality (20%), and completeness (20%) share the top position — security (15%) ensures the new feature introduces no vulnerabilities.

Dimension	Weight
Test Coverage	20%
Code Quality	20%
Completeness	20%
Security	15%
AI Review	15%
Performance	10%

Bug Fix

Use when you have a known bug to diagnose and fix. The pipeline starts with root-cause analysis before writing any code.

Analysis produces:

Document	What it contains
Diagnosis Brief	Known reproduction steps, affected area, initial error context
Task Breakdown (TASKS)	Fix subtasks
Regression Test Plan	Test cases that must reproduce and verify the original bug

Execution phases: Diagnose → Fix → Verify → Review

TIP

The Diagnose phase is unique to bugfix. The AI will first reproduce the bug, identify the root cause, and document its fix plan — before writing a single line of fix code.

Gate Score focus: Completeness and test coverage are weighted equally at 25% each — the fix must be thorough and backed by regression tests.

Dimension	Weight
Completeness	25%
Test Coverage	25%
AI Review	15%
Code Quality	15%
Security	10%
Performance	10%

Refactor

Use when you want to improve the internal structure of code without changing its external behavior — renaming modules, extracting abstractions, reducing duplication, etc.

Analysis produces:

Document	What it contains
Refactor Plan	Current structure analysis, target structure, behavior-preservation strategy, risk assessment
Task Breakdown (TASKS)	Refactoring subtasks

WARNING

Refactoring does not produce a test intent file, because no new functionality is being added. The gate's primary check is that all existing tests still pass.

Execution phases: Analyze → Refactor → Verify

Gate Score focus: Test coverage (30%) and code quality (30%) are equally weighted — the gate validates that structure improved while behavior stayed identical.

Dimension	Weight
Test Coverage	30%
Code Quality	30%
AI Review	15%
Security	10%
Completeness	10%
Performance	5%

Documentation

Use when you want AI to write or update documentation — README, API docs, architecture guides, user manuals, etc. This is the lightest pipeline with no code changes.

Analysis produces:

Document	What it contains
Document Outline	Chapter structure, content points for each section, target audience

Execution phases: Write → Review

INFO

Documentation skips automated testing and the verification phase entirely — only write and review phases run.

Gate Score focus: Test coverage, security, and performance do not apply. Completeness (35%) and AI review (35%) together account for 70% of the score — content quality is the only measure.

Dimension	Weight
Completeness	35%
AI Review	35%
Code Quality	30%

Improvement

Use when you want to iterate on an existing feature — better UX, performance optimization, adding an option, richer error messages. Behavior changes are expected but existing behavior must be preserved.

Analysis produces:

Document	What it contains
Improvement Spec	Current state analysis, improvement goals, Before/After comparison, backward-compatibility requirements
Task Breakdown (TASKS)	Improvement subtasks
Test Scenarios Plan	Tests for both unchanged existing behavior and new improved behavior

Execution phases: Design → Implement → Test → Review

Gate Score focus: All six dimensions apply. Code quality (25%) is slightly higher than the rest — ensuring the improvement doesn't degrade the existing implementation.

Dimension	Weight
Code Quality	25%
Test Coverage	20%
Completeness	20%
AI Review	15%
Security	10%
Performance	10%

Task

Use for engineering tasks that don't need architecture design — writing a migration script, adjusting CI configuration, adding environment variables, running a data backfill, etc.

Analysis produces:

Document	What it contains
Task Plan	Step-by-step execution plan, expected outputs, completion criteria

Execution phases: Execute → Verify (verification is optional)

INFO

Tasks do not generate automated test scripts. The AI will execute the task and optionally verify completion, but no formal test suite is expected.

Gate Score focus: Completeness (40%) carries the highest weight, focusing on whether the task was executed as planned. Test coverage and performance are not scored.

Dimension	Weight
Completeness	40%
AI Review	25%
Code Quality	25%
Security	10%

Research (Spike)

Use when you need to investigate a technical question or validate feasibility — evaluating a new library, comparing architectural approaches, building a proof-of-concept.

Analysis produces:

Document	What it contains
Research Brief	Research question, scope, constraints, key evaluation criteria

Execution phases: Research → Prototype (optional) → Document Findings

INFO

Spikes do not produce production code. The prototype phase is optional — it only runs if a PoC would help validate the research. The final deliverable is a research report with conclusions and recommendations.

Gate Score focus: Completeness (40%) and AI review (35%) together account for 75% of the score — the quality and thoroughness of the research report is what counts. No test coverage or performance scoring.

Dimension	Weight
Completeness	40%
AI Review	35%
Code Quality	15%
Security	10%

FAQ (Technical Q&A)

Use when you need to answer a technical question and preserve the answer — "How does X work?", "Why is Y failing?", "What's the correct way to configure Z?". Answers are stored in the knowledge base for future reuse.

Analysis produces:

Document	What it contains
Question Brief	Question context, relevant code snippets or error messages, related areas

Execution phases: Answer → Review Answer

Gate Score focus: Completeness (45%) and AI review (40%) together account for 85% of the score — entirely focused on answer accuracy and knowledge value.

Dimension	Weight
Completeness	45%
AI Review	40%
Code Quality	15%

Choosing the Right Type

What are you trying to do?
│
├─ Build something new for users?
│  └─→  feature
│
├─ Fix a known bug?
│  └─→  bugfix
│
├─ Make an existing feature better?
│  └─→  improvement
│
├─ Clean up the code without changing behavior?
│  └─→  refactor
│
├─ Write or update documentation?
│  └─→  documentation
│
├─ Execute a one-off engineering task (script, config, data)?
│  └─→  task
│
├─ Research a technology or validate a technical approach?
│  └─→  spike
│
└─ Answer a technical question (and save the answer)?
   └─→  faq

Gate Score Dimensions

All requirement types are evaluated against the same 7 dimensions, but the weights differ per type to reflect each type's quality priorities.

Dimension	Description	Scored for
Test Pass Rate	Unit & integration tests pass (100% / ≥95%)	feature, bugfix, refactor, improvement
Code Coverage	Line ≥80%, branch ≥70%	feature, bugfix, refactor, improvement
Static Analysis	Lint + type check pass	All types
Security	No high-severity vulnerabilities (Semgrep + Trivy)	Most types
Diff Risk	Auth/payment/migration files change → flagged	Most types
AI Review	Critic Agent assessment (advisory)	All types
Requirement Coverage	Supplementary requirements and open risks from the review phase are addressed	All types

About Requirement Coverage

Requirement Coverage applies to every requirement type, but it is a derived dimension — it is not listed in the per-type Gate configuration tables above because it is not a directly configurable weight. Its weight is derived from 30% of each type's "Completeness" dimension.

• Score = 1.0 (full marks): No high-severity unresolved open risks in the review phase → the most common outcome; appears at the outer edge of the radar chart
• Score = 0.0: High-severity supplementary requirements remain open → forces human review

In practice, Requirement Coverage shows as 100% for most executions. It only drops below full marks when the review-phase AI identifies critical missing requirements that were not subsequently addressed.

Score thresholds (configurable per project in WORKFLOW.md):

• ≥ 85 → Auto-approve and merge
• 60 – 84 → Requires human review on the Gates page
• < 40 → Auto-reject, AI fix loop triggered

High-risk changes always require human review

If a change touches authentication, payment, database migrations, or deployment scripts — human approval is always required, regardless of the score.

Tips

• Switching types after analysis starts will trigger a full re-analysis and clear existing analysis documents.
• feature vs improvement: Use feature for something entirely new; use improvement when enhancing something that already exists.
• task vs feature: Tasks have no design phase. If you need architecture decisions or API design, use feature instead.
• spike results feed naturally into feature or improvement requirements — reference the research report in your next requirement description.