Clarifications
Clarifications are questions raised against a focus area when the spec doesn't cover a decision that needs to be made.
A clarification is a question raised against a focus area when the spec is ambiguous, incomplete, or doesn't cover a decision that needs to be made in order to implement the work.
Where clarifications come from
Clarifications can be raised by:
- Penling's AI — during spec extraction, when the brief doesn't answer a decision point
- Your coding agent — during the build, when it encounters ambiguity the spec doesn't resolve
- Team members — at any point, when they need a decision before continuing
Anatomy of a clarification
A clarification has:
- A question — the decision that needs to be made
- A context — why the question arose and what the agent or team member was doing when it came up
- An answer — the resolution, once provided
- A spec update flag — whether the answer should be written back into the focus area spec
Answering a clarification
When a clarification is raised, the workspace member responsible for the focus area is notified. They read the question, provide an answer, and decide whether the answer should update the spec.
If the spec is updated, the change is reflected in the focus area immediately and visible to the coding agent on its next read.
Clarifications and the build
Unanswered clarifications block the agent's ability to progress on a focus area. This is intentional — rather than guessing at intent and potentially building the wrong thing, the agent pauses and surfaces the question.
This makes clarifications a healthy signal: a clarification is not a failure of the spec, it's the spec-refinement loop working correctly.
Tracking clarifications
Open clarifications are surfaced on the initiative dashboard and in the build timeline. You can filter to see all open clarifications across a workspace, making it easy to unblock agents working on multiple initiatives.