characterization-tool-for-git-workflows/PRD.md

# PRD — Characterization Tool for Git Workflows

## 1. Product Summary

**Product name:** Characterization Tool for Git Workflows

The Characterization Tool for Git Workflows is a web application that helps users create, manage, and review structured characterizations of Git workflows. The product replaces a manual spreadsheet-driven process with a guided, incremental workflow that helps users select categories, features, roles, options, enforcement levels, and attributes according to a predefined characterization framework.

The goal is to make Git workflow characterization easier, more consistent, less error-prone, and easier to revisit later.

## 2. Background and Context

The source workbook contains the characterization framework, including instructions, terminology, dictionaries, constraints, content examples, and catalogues. The app should treat this workbook as **reference framework data**, not as the primary editing interface.

A workflow characterization starts from a workflow description. The user identifies the workflow, optionally links to or pastes the workflow description, and then characterizes the workflow feature by feature.

The characterization is built incrementally. After completing one feature, the user chooses whether to characterize another feature or finish the workflow characterization.

## 3. Guiding Decisions

The following product and data decisions are part of the initial scope:

* Ignore `1.d Environment` because it is hidden in the `Framework` sheet.
* Use `0. Framework setup` as the correct category name and identifier. The `1` value in `Catalogues` should be treated as a typo.
* Use **Ruby on Rails 8**.
* Use **PostgreSQL**.
* Use **TailwindCSS** for styling.
* Use **Rails built-in authentication**.
* Support GitHub login through OAuth.
* Use **RSpec** as the testing tool.
* Use **Kamal** for deployment.
* Keep the interface simple and focused on easing workflow characterizations.

## 4. Goals

The app should:

1. Allow users to create, update, list, view, and delete Git workflow characterizations.
2. Guide users through the characterization process one feature at a time.
3. Preserve the structure and terminology of the characterization framework.
4. Help users select valid framework elements such as categories, features, roles, options, enforcement levels, and attributes.
5. Provide enough validation and guidance to reduce characterization mistakes.
6. Let users save unfinished work and resume later.
7. Let users review a completed characterization in a readable format.
8. Import and maintain framework reference data from the provided workbook.
9. Support user accounts and GitHub login.
10. Keep the product simple, fast, and usable without unnecessary complexity.

## 5. Non-goals for the Initial Version

The initial version should not attempt to:

* Automatically characterize an entire workflow using AI.
* Replace expert judgment in interpreting workflow descriptions.
* Support real-time multi-user collaborative editing.
* Provide a complex rules engine for all constraints on day one.
* Support multiple characterization framework versions unless required later.
* Build a separate frontend SPA.
* Build advanced analytics dashboards.
* Build a public workflow marketplace or repository.

## 6. Target Users

### Primary User: Workflow Analyst

A user who reads a Git workflow description and creates a structured characterization according to the framework.

Needs:

* Understand the framework while working.
* Characterize one feature at a time.
* Avoid invalid or inconsistent selections.
* Save progress and resume later.
* Review the characterization clearly.

### Secondary User: Reviewer or Researcher

A user who reviews existing characterizations, compares workflows, or uses the data for research.

Needs:

* Browse existing characterizations.
* Inspect selected features and supporting evidence.
* Export or reuse characterization data.

## 7. Core User Journey

1. User signs in.
2. User creates a new workflow characterization.
3. User provides:

   * Workflow name.
   * Optional workflow description URI.
   * Optional pasted workflow description text.
4. User starts the guided characterization process.
5. User selects or confirms high-level framework setup information.
6. User characterizes one feature:

   * Select category.
   * Select feature or sub-feature.
   * Select role, when applicable.
   * Select value or option.
   * Select enforcement level.
   * Fill required attributes, when applicable.
   * Add evidence excerpt or notes, when useful.
7. App validates the feature entry and shows warnings or missing information.
8. User saves the feature entry.
9. App asks whether the user wants to characterize another feature.
10. User repeats the process until done.
11. User marks the characterization as completed.
12. User reviews the completed characterization grouped by framework category.

## 8. Functional Requirements

### 8.1 Authentication and User Accounts

The app must support user accounts.

Users should be able to:

* Register with email and password.
* Sign in with email and password.
* Sign out.
* Reset their password.
* Sign in with GitHub.
* Link a GitHub account to an existing account where supported.

Each characterization must belong to a user. The author should be inferred from the current authenticated user.

### 8.2 Framework Data Import

The app must import framework reference data from the workbook.

Imported data should include:

* Categories.
* Features and sub-features.
* Feature options.
* Roles.
* Enforcement levels.
* Attributes and attribute requirements.
* Constraints.
* Terminology.
* Content examples.
* Catalogues.

The import process should preserve traceability to the workbook where practical, such as source sheet and source row.

The import process must apply the agreed data corrections:

* Ignore hidden `1.d Environment` from the framework.
* Normalize the framework setup category to `0. Framework setup`.

### 8.3 Characterization Management

Users must be able to manage their workflow characterizations.

A characterization must include:

* Workflow name.
* Author, derived from the current user.
* Optional workflow description URI.
* Optional workflow description text.
* Status: draft or completed.
* Timestamps.

Users should be able to:

* Create a characterization.
* List their characterizations.
* View a characterization.
* Edit characterization metadata.
* Delete a characterization.
* Resume a draft characterization.
* Mark a characterization as completed.
* Reopen a completed characterization for editing, if needed.

### 8.4 Guided Feature Characterization

The app must guide users through the characterization process feature by feature.

For each characterized feature, users should be able to select, when applicable:

* Category.
* Feature or sub-feature.
* Role.
* Value or option.
* Enforcement level.
* Attributes.
* Evidence excerpt.
* Notes.

The feature form should use dependent selections where useful:

```text
Category → Feature → Role → Value / Option
```

The app should make irrelevant fields unavailable or hidden when they do not apply.

After saving a feature entry, the user should be prompted to either:

* Characterize another feature.
* Return to the characterization summary.
* Finish the characterization.

### 8.5 Characterization Entry Editing

Users should be able to manage individual feature entries within a characterization.

Users should be able to:

* Add a feature entry.
* Edit a feature entry.
* Delete a feature entry.
* View feature entries grouped by category.
* See required attributes for the selected feature option.
* See terminology or examples that help them understand the selected feature.

### 8.6 Constraint Guidance and Validation

The app should help users avoid invalid or incomplete characterizations.

For the initial version, validation should focus on practical guidance rather than full formal constraint solving.

The app should support:

* Required fields.
* Required attributes for selected options.
* Duplicate prevention where the same feature option should not be added twice.
* Basic dependency warnings based on imported constraints.
* Clear messages explaining what is missing or inconsistent.

Examples:

```text
This option requires an attribute value for R<rr>.
```

```text
This feature depends on a framework setup selection that has not been added yet.
```

The app should save valid entries. For warning-level issues, the user may be allowed to save with warnings if the issue does not make the entry structurally invalid.

### 8.7 Review Page

The app must provide a readable summary page for each characterization.

The summary should show:

* Workflow name.
* Author.
* Description URI, if provided.
* Status.
* Number of characterized features.
* Entries grouped by category.
* Feature name.
* Selected role, when applicable.
* Selected option or value.
* Enforcement level.
* Attributes.
* Evidence excerpt.
* Notes.
* Validation warnings, if any.

### 8.8 Search and Filtering

The initial version should provide basic filtering for characterizations.

Users should be able to filter or search by:

* Workflow name.
* Status.
* Updated date, if practical.

Advanced search can be deferred.

### 8.9 Export

The app should support exporting a characterization.

Initial export formats:

* CSV.
* JSON.

A later version may support XLSX export matching the original matrix format.

## 9. UX and Design Requirements

The design should be simple, clear, and task-oriented.

Design principles:

* Prioritize clarity over density.
* Keep the user focused on the current feature being characterized.
* Avoid showing the entire framework at once unless the user is reviewing.
* Use progressive disclosure for advanced details.
* Make terminology and examples available near the form fields they explain.
* Use clear status indicators for draft, completed, and warnings.

Recommended layout for the main characterization workspace:

```text
Header
  Workflow name, status, progress

Left panel
  Workflow metadata
  Progress summary
  Existing entries grouped by category

Main panel
  Current feature form
  Validation messages
  Save / save and add another / finish actions

Side panel or expandable help
  Terminology
  Examples
  Constraint hints
```

TailwindCSS should be used to build a lightweight, consistent UI without introducing unnecessary frontend complexity.

## 10. Technical Architecture

### 10.1 Application Stack

* Ruby on Rails 8.
* PostgreSQL.
* TailwindCSS.
* Hotwire / Turbo / Stimulus for dynamic interactions.
* Rails built-in authentication.
* OmniAuth GitHub for GitHub login.
* RSpec for automated testing.
* Kamal for deployment.

### 10.2 Application Style

Use a Rails monolith.

Avoid a separate frontend application in the initial version. The app does not require SPA-level complexity.

Use Turbo and Stimulus for:

* Dependent selects.
* Inline validation feedback.
* Add-another-feature flow.
* Dynamic attribute fields.

### 10.3 Suggested Core Models

```text
User
Identity
WorkflowCharacterization
CharacterizationEntry
FrameworkCategory
Feature
FeatureOption
Role
Catalogue
CatalogueTerm
EnforcementLevel
FrameworkConstraint
ContentExample
TerminologyEntry
```

### 10.4 Data Ownership

Reference framework data is global and shared across users.

User-generated data belongs to the user who created it.

Initial authorization rule:

* Users can only manage their own characterizations.
* Admin-only framework editing can be deferred.

### 10.5 Framework Import Strategy

Create an import task that can be run locally or during setup:

```bash
bin/rails git_workflows:import_framework path=./data/systematic-characterisation.xlsx
```

The importer should be idempotent where practical.

At minimum, it should avoid creating duplicate categories, features, options, enforcement levels, and catalogue terms when run more than once.

## 11. Data Model Notes

### 11.1 Workflow Characterization

Represents one characterized Git workflow.

Important fields:

* `user_id`
* `name`
* `description_uri`
* `description_text`
* `status`
* `completed_at`

### 11.2 Characterization Entry

Represents one characterized feature within a workflow.

Important fields:

* `workflow_characterization_id`
* `feature_id`
* `feature_option_id`
* `role_id`
* `enforcement_level_id`
* `attributes_json`
* `evidence_excerpt`
* `notes`
* `position`

Use PostgreSQL `jsonb` for flexible attributes because different features require different attribute structures.

Example:

```json
{
  "R<rr>": "R0",
  "options": ["--rebase"],
  "development_line": "main"
}
```

### 11.3 Framework Constraints

The initial version should import constraints and expose basic warnings.

A later version may normalize constraints into a richer internal rule model.

## 12. Security and Privacy

The app must:

* Require authentication for characterization management.
* Restrict users to their own characterizations.
* Store GitHub OAuth identity data safely.
* Avoid exposing OAuth secrets.
* Use Rails defaults for CSRF protection, session management, and password security.
* Avoid storing unnecessary personal data.

## 13. Deployment

Use Kamal for deployment.

The deployment setup should include:

* Rails app container.
* PostgreSQL database.
* Environment variable management.
* Secret management.
* Persistent storage only where needed.
* SSL configuration.

For the MVP, deployment can target a single VM.

## 14. Success Metrics

The initial version is successful if:

* A user can create a complete characterization without editing the spreadsheet.
* A user can save a draft and resume later.
* The app can import the framework data from the workbook.
* The app guides users through valid feature selections.
* The app makes required attributes and basic constraint warnings visible.
* A completed characterization is easier to review than the original spreadsheet format.

Possible measurable indicators:

* Time to create a characterization.
* Number of incomplete entries prevented by validation.
* Number of characterizations completed.
* Number of resumed drafts.
* User-reported ease of use.

## 15. Risks and Mitigations

### Risk: Framework constraints are complex

Mitigation:

Start with basic validation and warning messages. Defer a full rules engine until the product proves useful.

### Risk: Spreadsheet import contains inconsistencies

Mitigation:

Track source sheet and source row. Normalize known issues during import. Report import warnings clearly.

### Risk: The UI becomes as complex as the spreadsheet

Mitigation:

Use a guided flow. Show only the current decision and relevant help. Keep review separate from editing.

### Risk: Attribute modeling becomes too rigid

Mitigation:

Use `jsonb` for entry attributes in the initial version. Normalize only after real usage patterns are clear.

### Risk: GitHub OAuth account linking creates duplicate users

Mitigation:

Treat GitHub login carefully. Prefer explicit linking for existing users.

## 16. MVP Scope

The MVP should include:

* Rails application setup.
* Authentication with email/password.
* GitHub login.
* Framework importer.
* Characterization CRUD.
* Guided feature characterization.
* Basic validation and warnings.
* Review page grouped by category.
* CSV and JSON export.
* Simple TailwindCSS UI.
* Kamal deployment configuration.

## 17. Future Enhancements

Possible future improvements:

* Workflow comparison view.
* XLSX export compatible with the original framework matrix.
* AI-assisted feature suggestions from pasted workflow descriptions.
* Full constraint rule engine.
* Admin interface for framework data.
* Framework versioning.
* Public/private characterizations.
* Collaborative review and comments.
* Audit history for characterization changes.