SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsescrever-prd

escrever-prd

Office & productivity

View repository

Updated 10-15 21:40

About this skill

Write PRD

Creates and edits feature PRDs. A PRD is a unit of product reasoning: the set of behavior and business rules whose decisions are explained together. It is a human document — the source of truth for product intent. It describes the feature completely in behavior and business rules; the AI consults it on demand for the why and implements it from the SPEC (derived from it by the sdd-especificar). The technical context for implementing comes from the TRD (loaded alongside during implementation). The references field connects PRDs to each other and to external resources when necessary.

The skill covers both the creation of the PRD and the editing of existing PRDs that have not yet been completed — PRDs with status: concluido are immutable and should not be edited by this skill.

Role of the PRD in the flow

The PRD fulfills two roles:

  1. Feature spec — a self-contained document of behavior and business rules, used to implement the feature
  2. State control — source of truth for the feature lifecycle, via the status field and the graph of depends_on

Principles that follow from this:

  • Immutability in concluido — when the status reaches concluido, the PRD freezes and becomes a historical record. Later behavior changes must open a new PRD, not edit a completed one
  • Progressive disclosure via depends_on — dependencies between PRDs are declared explicitly; the agent only reads a dependent PRD when the implementation context requires it
  • Separation of responsibilities — the PRD covers behavior and business rules; the TRD and ADR cover technical constraints, stack, and architecture decisions. The PRD references the technical artifact, but does not direct, size, or track it — the form of the PRD is decided by the product, not by execution
  • Stable IDs — USs and Milestones receive IDs (US01, Milestone 1...) that do not change after being assigned, because future artifacts (planning, tasks) reference them by these IDs

Input

The user provides a description of what they want to build, which may include:

  • Description of the problem or opportunity
  • Solution idea
  • Technical context
  • Known constraints

$ARGUMENTS — if provided, use as the initial description of the feature.

Execution Flow

1. Mode identification

First of all, identify whether the request is for creation or editing:

  • Creation — the user describes a new feature or does not reference any existing PRD
  • Editing — the user references a specific PRD (by number, name, or file) or requests adjustment/refinement of something existing

In edit mode:

  1. Read the referenced PRD in ./docs/prds/
  2. Check the status — if it is concluido, stop and notify the user that completed PRDs are immutable and behavior changes must open a new PRD
  3. For PRDs in rascunho, pronto or em-progresso, proceed with editing while preserving prd_number, already assigned US IDs and Milestones

2. Scope Analysis and Blocking Gaps

Before generating, perform two quick checks:

2a. Multiple feature detection

The unit test is not disconnection — it is self-sufficiency. A PRD covers one feature when each part explains itself and delivers something observable to the user. If the input has parts that pass this test separately, they are distinct features — even if dependent on each other. Dependency is normal and lives in the depends_on (a chained feature is still a feature of its own); it is not what prevents the split.

Sanity check: if the feature requires many product milestones (in practice, more than ~6), it is probably several features — reassess the split. Few milestones do not force anything: a small feature can have 1 or 2 legitimate milestones.

If multiple features are detected, propose a concrete split before generating:

Detectei 3 features no input. Sugiro criar:
  PRD-A: [nome da feature A]
  PRD-B: [nome da feature B]
  PRD-C: [nome da feature C]

Começamos pelo PRD-A?

Wait for confirmation or adjustment of the split. Internally record the list of pending PRDs.

2b. Blocking gaps

Check whether there is information without which the draft would be unusable — something impossible to infer reasonably. Examples of a real blocking gap: cannot determine the feature's domain or the system in which it operates.

If there is a blocking gap: one closed question (with options when possible), no interview. Any other gap — infer and mark it in the draft.

If there is none: generate immediately.

3. Draft Generation with Assumptions

Generate the complete PRD immediately, without waiting for more information. What was not provided is inferred and marked inline.

Assumption format:

- Token expirado → redirecionar para login *(premissa — confirme ou corrija)*

Use *(premissa — confirme ou corrija)* in any inferred content: rules, edge cases, acceptance criteria, negative scope, milestones. The user reviews concrete text — not answers to abstract questions.

Generation:

  1. Read the template in references/template-prd.md
  2. Generate the complete PRD filling in all sections
  3. Infer rules and edge cases that were not provided, marking each as an assumption
  4. Present the draft to the user for targeted review

Generation rules:

  • Use clear and objective language — avoid unnecessary jargon
  • Fill in all sections — mark what was inferred as an assumption; only use "To be defined" for what the user explicitly left open
  • The PRD is self-contained in behavior and business rule — not in a technical context. Stack, architecture, and patterns come from the TRD (loaded together during implementation); the Context section provides only a pointer when relevant, without duplicating the stack
  • Each feature must be a User Story (US) with a sequential ID (US01, US02...)
  • Each US must contain: a user story in the format "As a [persona], I want [action], so that [benefit]", Rules (business rules and expected behaviors), and Edge cases (anomalous situations with expected behavior)
  • Each US must have at least one Rule and one Edge case — infer the most likely ones when not provided, marking them as an assumption
  • Edge cases follow the format: "[anomalous situation] → [expected behavior]"
  • Acceptance criteria (§5a) cover functional and non-functional specific to the feature — response time, availability, and capacity are included when they have a business rationale (record the threshold and the why). The project's global NFRs (overall p95, uptime, encryption) live in the TRD, not in the PRD. Success metrics (baseline→target) go in §5b
  • Vague criteria such as "must work well" or "good performance" are not acceptable — rephrase them until they are objectively verifiable; if there is not enough data, mark them as an assumption
  • A milestone is a product milestone: a cohesive set of features that delivers something to the user — something that would be announced as an achievement, not an execution slice. Each milestone is defined by which USs it covers (by ID), by a justification of why it is a milestone (self-assessment: if the justification comes out forced, it is probably a disguised task or two squeezed milestones) and by an acceptance checklist (criteria from §5a filtered by the milestone's USs, checkable by the Approver after implementation). No minimum number of milestones; the ceiling of ~6 is the sanity signal for 2a. Do not detail technical tasks or execution order in the milestone — the decomposition (slices, tasks, order) belongs to the sdd-especificar
  • Include the Business Flow (§4, journey/process diagram where decision points are rules) only when the rule branching is not clear in the text. Technical topology (components/services, data model) does not go in the PRD — it stays in the TRD, in the ADRs or, when it is a local decision that is hard to reverse, in the slice's PLAN
  • The "Out of scope" section is mandatory — infer obvious exclusion items when not provided, marking them as an assumption
  • The "Decision Log" records product decisions and significant business assumptions. Architectural/technical decisions do not go in — they become an ADR
  • If the input brings a durable architectural decision (database choice, auth strategy, architectural pattern, foundational library), do not incorporate it as a product decision: flag that it is an ADR and suggest recording it via escrever-trd Decision Mode (docs/adrs/). The PRD can reference it in §8
  • The "References" section lists links to documentation, issues, related PRDs, APIs, designs or external resources mentioned in the context
  • The field references in the frontmatter must contain the same links as the References section in list format
  • US IDs (US01, US02...) and Milestone IDs (Milestone 1, 2...) are stable — once assigned they do not change, since future artifacts (planning, tasks) reference them by these IDs
  • In creation mode, the initial status when saving is always rascunho. In edit mode, preserve the current status of the PRD — transitions between pronto, em-progresso and concluido are made by future planning and execution skills

4. Dependency Mapping

Before presenting the PRD for final review:

  1. List the existing files in ./docs/prds/ (or in the path provided by the user)
  2. For each existing PRD, assess whether the current feature depends on something already specified in it — depends means that the implementation of this feature presupposes behavior, entity, interface or rule described in the other PRD
  3. Fill in the field depends_on in the frontmatter with the list of identified prd_number (e.g.: depends_on: ["001", "003"])
  4. Record in the "Decision Log" the criterion used to define each dependency — avoids reconstructing the reasoning in the future

Rules:

  • Dependency must be real and specific — do not list every "related" PRD or "of the same domain"
  • If there are no dependencies, keep depends_on: []
  • The loading of dependent PRDs is on demand (progressive disclosure) — do not include their content in the current PRD

5. Targeted Refinement

Apply the corrections requested by the user to the draft — corrected assumptions, adjusted scope, refined rules. Repeat until approval.

If the review changes the feature scope, reassess depends_on before saving — a feature that gains or loses responsibilities may gain or lose dependencies.

6. Save File

In creation mode, save the new PRD:

  1. Determine the next number: list the existing files in ./docs/prds/ and identify the highest number used (format NNN). The next PRD receives the next sequential number. If no PRD exists, start with 001.
  2. Name the file: NNN-[nome-em-kebab-case].md (e.g.: 003-autenticacao-oauth.md)
  3. Default location: ./docs/prds/
  4. If the user specified another path, use the provided path
  5. Create the directory if it does not exist
  6. Fill in the field prd_number in the frontmatter with the assigned number (e.g.: 003)

In edit mode, overwrite the original file preserving prd_number, file name, current status and already assigned US and Milestone IDs. New USs receive the next available sequential ID.

7. Multi-PRD Continuity

After saving, check whether there was a proposed split in step 2a with pending PRDs.

If so:

PRD-A salvo. Continua com PRD-B: [nome da feature B]?

Upon confirming, start the cycle for the next PRD — taking advantage of the previous PRD's decisions as context for more precise inferences (same stack, same system, same detected patterns).

Repeat until all PRDs from the split are saved or the user interrupts.