Requirements Engineering

/pulse-re (in Codex $pulse:pulse-re) is the bridge between Business Analysis (the Why) and Planning (the How). It transforms the validated business analysis into structured, measurable, tech-agnostic requirements that a human or AI architect can actually design against.

Input: _devprocess/analysis/BA-{PROJECT}.md (Project-BA, if any) plus the matching Item-BA in _devprocess/analysis/, where one exists. For the first epic of a new project, the Project-BA is the source and /pulse-re opens the epic without an Item-BA; a later epic or feature comes from its own Item-BA. The Project-BA supplies personas, value dimensions, and KPIs by ID.

Output: an epic, features, and architect-handoff.md as files in the repository, and one record on the board per item so everyone sees its state. Every spec carries issue: (the item number) and ba-ref: in its front matter; the Item-BA stays in analysis/ as audit trail.

Why this phase exists

Most teams skip Requirements Engineering. The BA produces "what we want to build," someone writes a Notion page, and the next day engineers are picking a framework. Two failure modes follow from that shortcut.

Tech bleeds into the problem statement. "We need OAuth" gets written instead of "users must prove identity." Now the requirement is coupled to a technology before anyone has decided whether that technology fits.

Success becomes unmeasurable. Features ship with Definition-of-Done lines like "users love it" that no test, gate, or agent can ever verify. The result is a backlog full of items nobody can say are finished.

Requirements Engineering exists to catch both, systematically, before they contaminate the architecture.

The translation chain

Every output of RE descends from something in the BA. The skill enforces traceability. If a user story has no BA source, the skill flags it and sends you back to /pulse-ba rather than inventing new requirements on the fly.

BA element                    →  RE element
──────────────────────────────────────────────────────
HMW question                  →  Epic Hypothesis Statement
Functional needs              →  User Stories (functional)
Emotional needs               →  User Stories (emotional)
Social needs                  →  User Stories (social)
Jobs to be Done per level     →  User Story motivation
Critical Hypotheses           →  Leading indicators of the epic
Idea Potential axes           →  Priority label P0 / P1 / P2
Value Proposition             →  Definition of Done context

RE does not create new requirements out of thin air. It structures what the BA already surfaced.

Epic Hypothesis Statement

The Epic is the strategic container. It is not a "big feature." It is a hypothesis about value, written as full prose. The skill rejects fill-in-the-blank templates because they reduce a strategic decision to a Mad Libs exercise.

---
title: AI agent core
issue: 12
ba-ref: ../../analysis/BA-agent-core.md
---

# Epic: AI agent core

## Hypothesis

For solo founders running a B2B SaaS support inbox, who currently
spend two to four hours each day triaging tickets that mostly say
"how do I reset my password?", the AI agent core is a context-aware
ticket triage layer that auto-resolves the top ten password and
billing scenarios so the founder gets back at least an hour a day.
Unlike Zendesk macros, which the founder has to author and maintain
by hand, the agent core learns from the founder's resolution
history without configuration.

The hypothesis is one paragraph of prose, not a six-line template. The skill rejects formats like For {x} who {y} the {z} is a ... because they hide thin reasoning behind structure. A real hypothesis explains the user, the problem, the solution category, the primary value, the current alternative, and the unfair advantage in actual sentences.

Identity. The file is _devprocess/requirements/epics/EPIC-{nn}-{slug}.md: its name starts with the epic's ID, which pulse number --apply gives it (see File names and IDs). The record on the board links it, and its item number is what pulse commands take. Status lives in the record, never in the file.

Feature structure

Under each epic, features are the units that get implemented. A feature is what a team can ship in one coherent increment. Each one is a spec file in _devprocess/requirements/features/FEAT-{ee}-{nn}-{slug}.md, and its record on the board hangs under the epic's. When one feature needs another first, that is a "blocked by" link between the records, never prose.

---
title: Auto-resolve password reset tickets
issue: 14
parent: ../epics/EPIC-01-agent-core.md
ba-ref: ../../analysis/BA-agent-core.md
subtype: user-facing
priority: P1
effort: M
risk: []
---

# Feature: Auto-resolve password reset tickets

## Feature description
{Goal: what changes for whom, and why}

## Scope
- In: {what this feature does}
- Out: {what it deliberately does not do}

## User stories
| Role | Want | So that | Job type |

## Requirements
- FR-01: WHEN {trigger} THE SYSTEM SHALL {response}.
- FR-02 (unchanged): THE SYSTEM SHALL {keep what works today}.

## Success criteria
| ID | Criterion (tech-free) | Target | Measurement |

## Non-functional requirements
| Category | Target (with a number) | Notes |

## Architecturally Significant Requirements
| ID | Classification | Constraint | Quality attribute |

## Assumptions and dependencies
- {an assumption, or a skipped gap with the default we build on}

## Open questions
- [CLARIFY: only what the team keeps open on purpose]

## Activation Path
- Type: command | route | UI-element | endpoint | scheduled-job | tool | hotkey | public-API
- Identifier: `<command name | route path | URL | symbol name>`

## Definition of Done
- [ ] Every FR has a green test named after its id

Requirements in EARS. Each requirement is one numbered sentence with an uppercase SHALL: WHEN <trigger> THE SYSTEM SHALL <response>, IF <unwanted condition> THEN THE SYSTEM SHALL <response>, WHILE <state> THE SYSTEM SHALL <response>, or THE SYSTEM SHALL <what always holds>. Edge cases and error behavior are requirements of their own; what must keep working is marked (unchanged). One line per requirement keeps it testable: each FR becomes one test, named after its id, written before the code. Given/When/Then stays available for a multi-step flow.

The tree lives in the repository. parent: links the feature to its epic, and the epic lists its features (with their fixes and improvements) under ## Items. pulse new --parent sets issue: and parent: in the spec and adds its line to ## Items; pulse check (C9) keeps them in step. A spec written from the template names its parent before it is registered: C9 lets a spec without an issue number do that, so pulse check stays clean on the first commit of the specs. The file name carries the tree as well: write each spec under its slug, run pulse number --apply before the commit, and every spec starts with its ID (EPIC-01, FEAT-01-02, FIX-01-02-01); C10 reports one that does not.

Risk flags. risk: [auth, security, data-migration, public-api, new-dependency] records consequential choices. Preserve them in the Plan and final review. They add no routine early approval; a necessary decision outside the authorized task still goes to the person.

Frontmatter rule. Status, claim, and dependencies do not live in the frontmatter; the record carries them. The frontmatter holds identity (title, issue), document links (parent, ba-ref), planning inputs (priority, effort, risk), and the activation contract (subtype: user-facing | library, default user-facing). pulse new writes issue: and parent:. See Where things live.

Feature subtype. Two values:

• user-facing (default) -- anything an end user reaches: UI, CLI command, API endpoint, scheduled job, agent tool, plugin command, hotkey. Definition of Done MUST list a documented trigger.
• library -- public API consumed by other code (function, class, module, package). No direct end-user trigger. Definition of Done MUST list the exported symbol(s) and the documentation entry.

A FEATURE that builds a backend module without any caller is not a FEATURE -- it is infrastructure, and belongs as an IMP, not a FEAT with status Done. The Activation Path entry forces the question "how does anyone reach this code?" before the FEATURE moves out of specification.

/pulse-build verifies both the reachability and the activation path before an item may close.

Fixes and improvements hang under their feature. Their spec is a short file in _devprocess/requirements/fixes/ or improvements/, named after its ID (FIX-04-02-01 is the first fix of feature FEAT-04-02): symptom, root cause as a causal chain, and regression test for a fix; description, reason, and success criteria for an improvement.

User stories across three levels of need

Human needs stack in three layers. The skill writes user stories on all three layers where the need exists, because a feature that serves only the functional layer is dramatically less sticky than one that serves the emotional and social layers too. The method that surfaces these three layers is the Jobs to be done card.

Functional is what the user is trying to do. Emotional is how they want to feel while doing it. Social is how they want to be seen while doing it.

For a shared-expense app inside a roommate household:

• Functional. "As a roommate I want to record a shared purchase so that the split math is automatic."
• Emotional. "As a roommate I want the split to feel fair without awkward conversations so that the shared flat stays calm."
• Social. "As a roommate I want other flatmates to see I always pay my share so that my reputation stays intact."

The third line is where retention comes from. The agent probes explicitly for the emotional and social layer when it drafts user stories from BA needs. If the BA did not capture those layers, the agent sends you back to the Jobs to be Done method card to fill them.

Tech-agnostic Success Criteria

This is the rule the skill is most aggressive about. Success Criteria must be free of technology vocabulary.

Bad:

• "User authenticates via OAuth 2.0."
• "Data is stored in PostgreSQL with 24h retention."
• "REST endpoint returns 200 OK within 300ms."
• "React component loads in under 2s."

Good:

• "A user can prove identity without entering a password more than once a week on the same device."
• "Data a user deletes becomes irrecoverable within 24 hours."
• "A user receives a visible response within 300ms of any list interaction."
• "The first list view becomes interactive within 2s on a mid-range phone on 3G."

Why the rule matters: Success Criteria are the contract between the user and the team. If the contract references OAuth, you cannot swap it for a magic-link flow without renegotiating. If the contract references React, you have locked the stack before the architect has seen the problem.

Technical details live in the Technical NFRs section of the same Feature, clearly separated, and in the ADRs that follow in planning. See Tech-agnostic Requirements for the full ruleset.

ASRs: Architecturally Significant Requirements

An ASR is a requirement whose realisation shapes the architecture. You cannot satisfy it by editing one module in isolation. Common examples:

• Performance targets (latency, throughput, percentile budgets)
• Security constraints (data classification, auth model)
• Compliance constraints (GDPR, HIPAA, SOC2)
• Availability and recovery targets (SLA, RPO, RTO)
• Scale targets (concurrent users, data volume)
• Integration constraints (must talk to system X, must not talk to Y)

The skill marks every ASR Critical or Moderate. A Critical ASR usually becomes a decision record in planning.

The clarifying interview

The skill asks until the spec is one an agent can plan from without asking back: goal, scope with what is out, every requirement, edge cases, unchanged behavior, the signal for done, the four NFR categories, and constraints. There is no question budget. One question per turn, with options and a recommendation. A thin answer gets a sharper question first (a concrete example, the future without the problem, the opposite); the same question never comes back in other words.

When you do not know an answer, the skill proposes the method that finds it (below) and helps you prepare it. You can always skip: the gap goes into the spec as an assumption with the default the skill recommends, marked (skipped), and the spec stays plannable. Only a question you want to keep open stays as [CLARIFY: ...], and that holds the spec back until someone answers it.

How the agent proposes methods in the dialog

Like the BA, this skill spots gaps in your input and suggests the method that will close them. You run the method, you come back with data, the skill continues. Common triggers and the matching cards:

• Epic Hypothesis missing the current alternative. User journey focused on the "before" phase, so you can see how the user solves the problem today without your product.
• Feature has only functional user stories. Jobs to be done to surface the emotional and social layers so the stories stop feeling hollow.
• A story or benefit has no source in the BA. Qualitative interview or User motivation analysis to anchor it in real evidence.
• Technical NFR reads "fast" or "secure" without a number. Expert conversations with the engineering or operations team to get a concrete target.
• ASR is suspected but unverified. Expert review so you can confirm feasibility before writing the ADR.
• Success Criterion cannot be made measurable. Test grid or Value proposition quantification for a baseline you can test against.
• Critical Hypothesis from BA has no test plan. Pick the cheapest falsifier: Wireframes, storyboards, and paper prototypes, Wizard of Oz, or Appearance prototype.
• Risk blind spots before commit. Pre-mortem before the team locks resources.

Priority: from Idea Potential to P0 / P1 / P2

The BA scored Idea Potential on three axes: User Value, Transferability (Scalability), and Feasibility. Requirements Engineering collapses those three scores into a single priority label per feature.

Priority	Criteria	Meaning
P0	High User Value and High Feasibility	Must ship in v1
P1	Moderate across axes, or high value with risk	Should ship in v1 if time allows
P2	Low value or blocked feasibility	Backlog or follow-up

The label is visible on every Feature card so the architect knows immediately which features are load-bearing for the MVP.

Quality gates

Pulse validates the published spec before planning, including a spec on its item branch. The six rules answer the mechanical half of "can an agent plan from this". pulse check --spec <path> ... applies them to files in your working tree without reading the board; one --spec takes several paths and repeated flags add paths. /pulse-re runs this before publication:

Rule	Checks
R1	the spec is published and names its item (issue:)
R2	every mandatory section of its type is there and not empty
R3	no placeholder, no open [CLARIFY], no TODO outside the sections filled at the end
R4	at least one requirement, each a list line that starts with its id, such as - FR-01: WHEN ... THE SYSTEM SHALL ... (the id plain, bold, or in backticks), in EARS form with SHALL
R5	success criteria without technology terms, every NFR with a number
R6	priority P0 to P2 and effort XS to L (split XL first)

pulse new applies R2 to R6 before attaching a work item's spec and reports findings that must be fixed first. pulse check --spec <path> ... applies the same content rules locally; an epic needs R1 only. A valid published work-item spec is ready for planning without a separate spec merge.

The judgment half stays with the interview and review: every prioritized need has a story, emotional and social layers were probed, success criteria measure an outcome for the user.

See Verification Gates for the full gate mechanic.

The architect handoff

The final artifact is architect-handoff.md, a single document that planning will consume. It contains the Epic Hypothesis, the Feature summary table with priorities, the full list of Critical ASRs, the Technical NFRs with numbers, the open questions for the architect, and the Critical Hypotheses from the BA that are still unvalidated.

Every item is on the board from the moment the skill names it, as a draft (pulse new feat "<title>" --draft), so the team sees a spec in progress and who writes it; an issue you name becomes the draft instead (--issue <n>). Before it writes, the skill checks the open drafts and items for overlap and asks you when one covers the same goal.

Reserve each draft first to obtain its number, then create its <type>/<n>-<slug> branch from the fetched base. The skill validates the spec, runs pulse number --apply, commits it with docs(re): <title> and Refs: #<n>, and pushes. It attaches each published spec to its existing draft, parents first: pulse new epic "<title>" --spec <path> --issue <n>, then pulse new feat "<title>" --parent <epic> --spec <path> --issue <n>. --blocked-by records prerequisites. Commit and push the metadata that registration writes, on that same branch.

Published specs pass R1-R6 and continue into planning. For each ready feature, improvement or fix, the skill plans it in the same session without asking; an epic gets no implementation Plan. Planning claims the item and can proceed while prerequisites wait; building waits for their integration. After pulse check --plan <path> passes and the Plan is published, continue with /pulse-build <n> or an explicitly requested pulse go for the ready backlog. Spec, Plan and implementation stay together on the item branch. No PR or early person approval is needed.

The harness's permissions still apply to these operations. Claude Code may ask before pulse status, pulse check, git add, commits, pushes and pulse new; see Fewer prompts in Claude Code. Codex's sandbox may require permission for shared Git writes or network access. Keep session markers and real hooks intact.

Final integration approval is automatic by default. A person with repository write access may choose manual approval. The session names pulse approve <n> for your own terminal or the result action in the Map; it never operates that lever itself. The automatic policy uses the same head, base and evidence checks. That policy does not authorize destructive removal.

Read the skill file

skills/pulse-re/SKILL.md on GitHub.

Further reading

• Tech-agnostic Requirements. Full ruleset for keeping technology out of requirements.
• Planning. The next phase, where ASRs become ADRs.
• Discovery methods, Ideation methods, Validation methods. Method cards the agent references when you have gaps in the BA.