Skip to content

docs: explain how to provide input documents to the agent (#250) - #445

Open
valter-silva-au wants to merge 1 commit into
awslabs:mainfrom
valter-silva-au:task/TASK-00029
Open

docs: explain how to provide input documents to the agent (#250)#445
valter-silva-au wants to merge 1 commit into
awslabs:mainfrom
valter-silva-au:task/TASK-00029

Conversation

@valter-silva-au

Copy link
Copy Markdown

Summary

Closes #250.

The writing-inputs guides explain what a Vision Document and Technical Environment Document are and how they feed each AI-DLC stage, but never tell the user the mechanical step of how to hand a document to the agent or where to place it. As reported in #250, a user who asked "where do I put a vision document?" got a confused, non-definitive answer.

This adds the missing instruction, matching the fix @leandrodamascena outlined in the issue thread.

Changes

Add a short "How to Provide … to the Agent" section near the top of both:

  • docs/writing-inputs/vision-document-guide.md
  • docs/writing-inputs/inputs-quickstart.md

The section states the intended flow: place the document anywhere in your project and reference it in your initial request (e.g. read ./vision.md and start the AI-DLC workflow), or paste its contents into chat — no enforced folder convention.

Docs-only and additive; no rules, code, or behavioral change. (The issue also floated a tweak to requirements-analysis.md, but its Step 4 already instructs the agent to use "existing requirements documents (search workspace if mentioned)" and "pasted content or file references", so the genuine remaining gap was the user-facing docs.)

User experience

  • Before: The guides describe the documents thoroughly but never say where to put one or how the agent picks it up; users are left guessing and the agent gives non-definitive answers.
  • After: Both entry-point docs state up front how to provide an input document — reference it by path in the initial request, or paste it — and that no specific folder is required.

Checklist

  • I have reviewed the contributing guidelines
  • I have performed a self-review of this change
  • Changes have been tested
  • Changes are documented

Test Plan

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

The writing-inputs guides describe what a Vision Document and Technical
Environment Document are and how they feed each AI-DLC stage, but never
state the mechanical step of how to hand a document to the agent or where
to place it. Users asking "where do I put a vision document?" got
non-definitive answers (awslabs#250).

Add a "How to Provide ... to the Agent" section near the top of both
vision-document-guide.md and inputs-quickstart.md: place the document
anywhere, reference it in the initial request (e.g. "read ./vision.md and
start the AI-DLC workflow"), or paste it into chat — no enforced folder
convention.
@valter-silva-au
valter-silva-au requested a review from a team as a code owner June 27, 2026 06:09
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jun 27, 2026
@valter-silva-au

Copy link
Copy Markdown
Author

Heads-up on CI: the Security Scanners workflow (gitleaks/grype) shows red, but it's failing on main independently of this PR — the scheduled runs on main are red too, and this change is docs-only (+22 lines of markdown, no secrets or dependency changes). The separate gitleaks/grype checks that scan this PR's content pass, as do Markdown Lint, the contributor-statement check, and PR-title validation. Happy to rebase if you'd like once that workflow is addressed on main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Issue: Agent does not know what to do with a vision document

1 participant