---
name: to-project-context
description: Create or update project-context.md and canonical-terms.md after product discovery or PRD work. Use when the user wants to clarify product context, user personas, platform targets, constraints, domain vocabulary, canonical terms, or prepare stronger source-of-truth documents before user journeys, screen maps, wireframes, UX/UI briefs, guardrails, or implementation planning.
---

# To Project Context

Create two source-of-truth documents that make product work more deterministic:

- `project-context.md` - product context, users, platforms, constraints, assumptions, risks, and open questions.
- `canonical-terms.md` - approved vocabulary for the product, domain concepts, user roles, objects, states, actions, and terms to avoid.

Default output path:
- Use `docs/project-context.md` and `docs/canonical-terms.md` when a `docs/` directory exists or when source documents already live in `docs/`.
- Otherwise use `project-context.md` and `canonical-terms.md` at the project root.
- If the user gives explicit paths, use those paths.

## Source Discovery

Before asking questions, inspect the project and read existing product truth when present:

- `docs/product-idea.md`
- `docs/prd.md`
- `docs/user-journey.md`
- `docs/screen-map.md`
- `docs/ux-ui-generation-brief.md`
- `docs/development-plan.md`
- `README.md`
- `CODEX.md`
- issue descriptions, project notes, or attached docs if provided by the user

If an answer is discoverable from project files, use the files instead of asking. Cite the source file in the output when useful.

## Grill-With-Docs Mechanics

Use the Matt Pocock-style grilling approach, adapted for documents:

1. Walk the product context decision tree branch by branch.
2. Resolve dependencies in order: product purpose -> users -> platforms -> core scenarios -> constraints -> terms.
3. Ask only one question at a time when information is missing and blocking.
4. For every question, include a recommended answer based on the evidence.
5. Do not ask questions that can be answered by reading the project files.
6. Do not continue into PRD, screen map, wireframes, code, or implementation unless the user explicitly asks.
7. Stop grilling once the documents can be created with clearly labeled assumptions.

## Context Decision Tree

Clarify these areas, using documents first and questions only when needed:

1. Product identity
   - product name
   - product category
   - one-sentence purpose
   - desired user outcome

2. User personas
   - primary user
   - secondary users, if any
   - user skill level
   - user motivation
   - user pain points
   - decision maker vs end user, if different

3. Platform targets
   - web, mobile web, iOS, Android, desktop, browser extension, API, admin tool, or other
   - primary device and viewport assumptions
   - accessibility or localization requirements
   - hosting/deployment constraints, if known

4. Product boundaries
   - MVP scope
   - out-of-scope features
   - non-goals
   - risky assumptions
   - dependencies on external services

5. Operational constraints
   - payment, privacy, personal data, auth, roles, admin access, notifications, analytics, legal, or compliance constraints
   - content, language, geography, brand, or provenance restrictions
   - technical constraints that affect product decisions

6. Canonical terms
   - user-facing labels
   - internal domain terms
   - entities and objects
   - roles
   - states
   - actions
   - terms to avoid
   - synonyms that must collapse into one canonical term

## Output: project-context.md

Create or update `project-context.md` with this structure:

```markdown
# Project Context

## 1. Product Summary

## 2. Product Purpose

## 3. Target Users

## 4. User Personas

## 5. Main User Problems

## 6. Desired User Outcomes

## 7. Platform Targets

## 8. Core Scenarios

## 9. MVP Boundaries

## 10. Out of Scope

## 11. Constraints

## 12. Assumptions

## 13. Risks

## 14. Open Questions

## 15. Source Notes
```

Keep the document concise, decision-useful, and grounded in source files. Label inferred content as assumptions.

## Output: canonical-terms.md

Create or update `canonical-terms.md` with this structure:

```markdown
# Canonical Terms

## 1. Product Name

## 2. User Roles

## 3. Core Domain Objects

## 4. User Actions

## 5. Product States

## 6. Screen / Flow Names

## 7. Approved User-Facing Terms

## 8. Internal Terms

## 9. Synonyms to Normalize

## 10. Terms to Avoid

## 11. Open Vocabulary Questions
```

For each important term, prefer this format:

```markdown
### Canonical Term
- Meaning:
- Use when:
- Avoid:
- Notes:
```

## Rules

- Preserve existing useful content when updating files.
- Do not invent product logic silently.
- Do not add features outside the existing product scope.
- Do not write application code.
- Do not create frontend components.
- Do not create PRD, screen map, wireframes, UX/UI brief, or implementation plan unless separately asked.
- Keep Ukrainian product copy natural when the project is Ukrainian-language.
- Keep technical filenames, paths, commands, and API names unchanged.
- If source files conflict, report the conflict and ask which source wins.
- If information is missing but not blocking, proceed with a clearly labeled assumption.
- If information is blocking, ask one question and wait.

## Verification

After creating or updating files:

1. Re-read both output files.
2. Check that `project-context.md` includes users, platforms, constraints, assumptions, risks, and open questions.
3. Check that `canonical-terms.md` includes approved terms, synonyms to normalize, and terms to avoid.
4. Run `git diff -- <output files>` when in a git repository.
5. Report changed files and unresolved questions.