paw-spec-research

To document system behavior for specification writing, you can use spec research to collect behavioral descriptions, data flows, API behaviors, user workflows, and business rules, using evidence from documentation and the codebase to produce a structured research artifact.

The best way to identify open unknowns during system behavior research is to document factual findings alongside evidence sources and explicitly flag any unanswered behavioral questions as open unknowns in the final research artifact.

You generate a SpecResearch.md file by running the spec research process within a PAW subagent session. The process collects behavioral artifacts and outputs the file at .paw/work/<work-id>/SpecResearch.md.

Yes, you can use spec research to answer factual questions about existing system behavior. It specifically covers API behaviors, data flows, user workflows, and business rules by gathering evidence directly from your documentation and codebase.

You need evidence from existing documentation and the codebase to document system behavior for specs. These sources provide the factual basis for behavioral descriptions, data flows, API behaviors, user workflows, and business rules.

You should not use spec research when you need to design new system features rather than document existing behavior, or when your project lacks existing documentation and a codebase to use as evidence sources for behavioral findings.