Editing Requirements

Learn how to edit and update existing requirements using inline editing and the details panel.

Overview

All requirement fields can be edited after creation using two methods:

1. Inline Editing - Quick edits directly in Details tab
2. Full Edit Modal - Complete form for complex changes

Editable Fields:

• Title (text) and description
• Parent relationships (add/remove multiple parents)
• Type (with hierarchy restrictions)
• Priority, status, owner
• JIRA link and change notes
• All custom metadata fields

Inline Editing (Details Tab)

The Details tab provides quick inline editing for common fields without opening a modal.

How Inline Editing Works

1. Select Requirement - Click requirement in List tab tree
2. Switch to Details Tab - Click "Details" in right panel
3. Click Edit Button - Each field has a small "Edit" button
4. Modify Field - Input appears inline
5. Save/Cancel - Save (✓) or Cancel (✕) buttons appear

Editable Fields in Details Tab

Quick Edit Fields:

Field	Type	Edit Button Location
Title (Text)	Text area	Next to requirement title
Type	Dropdown	Next to requirement type badge
Status	Dropdown	Next to status badge
JIRA Link	Text input	Next to JIRA icon
Change Notes	Text area	In Change section

Field-Specific Editing:

Title (Text) Field

Current: "Engine shall generate 300 HP"
[Edit] ← Click to edit

When editing:
┌─────────────────────────────────────────┐
│ Engine shall generate 300 HP at 6000 RPM│  ← Editable text area
└─────────────────────────────────────────┘
[✓ Save] [✕ Cancel]

• Input: Multi-line text area (expands as needed)
• Validation: Required field (can't be empty)
• Best Practice: Keep concise but specific

Type Field

Current: System Requirement (SYS)
[Edit] ← Click to edit

When editing:
┌──────────────────────────────┐
│ ▼ Select requirement type... │
│   Customer Request (CR)      │
│ ✓ System Requirement (SYS)   │  ← Currently selected
│   Subsystem Requirement (SUB)│
│   Function Requirement (FUN) │
└──────────────────────────────┘
[✓ Save] [✕ Cancel]

• Input: Dropdown (hierarchy-appropriate types only)
• Validation: Must be valid type in organization hierarchy
• Effect: Changes custom ID (e.g., SYS-001 → SUB-001)

Type Change Impact

Changing type regenerates the custom ID and may affect child requirements. Verify hierarchy compatibility first.

Status Field

Current: Draft
[Edit] ← Click to edit

When editing:
┌──────────────────────────────┐
│ ▼ Select status              │
│ ── Pre-Implementation ──     │
│ ✓ Draft                      │  ← Currently selected
│   In Review                  │
│   Approved                   │
│ ── Implementation ──         │
│   Accepted (Ready for Dev)   │
│   Implemented                │
│   Verified                   │
│ ── Terminal ──               │
│   Rejected                   │
│   Deferred                   │
│   Deprecated                 │
└──────────────────────────────┘
[✓ Save] [✕ Cancel]

• Input: Dropdown with grouped options
• Options: Draft, In Review, Approved, Accepted, Implemented, Verified, Rejected, Deferred, Deprecated
• Transitions: Only valid transitions are allowed (e.g., Draft can go to In Review, not directly to Verified)
• Color Coding: Each status has a distinct color badge (gray, blue, purple, green, red, orange)
• Acceptance Gate: Moving to "Accepted" records who accepted and when (audit trail)
• Use Case: Track requirement lifecycle per ISO/IEC/IEEE 29148

See Requirements Lifecycle for the complete state machine and transition rules.

JIRA Link Field

Current: PROJ-1234
[Edit] ← Click to edit

When editing:
┌─────────────────────────────────┐
│ PROJ-1234                       │  ← Editable text input
└─────────────────────────────────┘
[✓ Save] [✕ Cancel]

• Input: Text field
• Format: Free-form (typically JIRA issue key)
• Best Practice: Use consistent format (e.g., PROJECT-123)
• Integration: Clickable link to JIRA (if configured)

Change Notes Field

Current: Initial draft created
[Edit] ← Click to edit

When editing:
┌─────────────────────────────────────────┐
│ Updated power requirement from 250 HP   │  ← Editable text area
│ to 300 HP based on customer feedback    │
└─────────────────────────────────────────┘
[✓ Save] [✕ Cancel]

• Input: Multi-line text area
• Use Case: Document reason for changes (audit trail)
• Best Practice: Be specific about what changed and why

Edit Button Styling

All edit buttons have consistent styling:

┌──────────┐
│ 📝 Edit  │  ← Icon + text, easy to spot
└──────────┘

• Padding: Comfortable click target
• Icon: Pencil/page icon for clarity
• Spacing: No overlap between icon and text
• Hover: Color change for feedback
• Transition: Smooth animation

Full Edit Modal

For complex edits affecting multiple fields, use the full edit modal.

Opening the Modal

From Tree View:

1. Click requirement in List tab tree
2. Click "Edit" button in Details tab action buttons (bottom)

What Opens:

• Full requirement edit form
• All fields editable simultaneously
• Same modal as "New Requirement" but pre-populated

Modal Features

Editable Fields:

• Title (text)
• Type
• Description (rich text area)
• Parent selection (single parent for hierarchy)
• Priority (High, Medium, Low)
• Status (lifecycle state)
• Owner (assign team member)
• JIRA link
• Change notes

Benefits of Modal:

• Edit multiple fields at once
• See all field validation together
• Change parent and type simultaneously
• Larger text areas for descriptions

Saving Changes

Save Button: Click "Save" to apply all changes

Validation:

• Required fields (title, type) must have values
• Type must be compatible with selected parent
• Circular parent references prevented

Result:

• Changes saved to database
• Tree view updates (if hierarchy changed)
• Details panel refreshes
• Success toast notification

Managing Parent Relationships

Adding Multiple Parents

Requirements can have multiple parents with different relationship types.

See: Parent Relationships Guide for complete documentation.

Quick Steps:

1. Select requirement → Details tab
2. Scroll to "Parent Requirements" section
3. Click "+ Add Parent" button
4. Select parent requirement from dropdown
5. Choose relationship type (derives_from, refines, implements, etc.)
6. Add link rationale (optional but recommended)
7. Click "Add Parent"

Result: New parent added to list, existing parents preserved

Removing Parents

Steps:

1. Find parent in "Parent Requirements" list
2. Click "Remove" button next to that parent
3. Relationship deleted immediately (no confirmation)

What's Removed:

• The specific parent relationship link
• Link rationale (if any)

What's Preserved:

• Parent requirement (unchanged)
• Child requirement (unchanged)
• Other parent relationships (if any)

Hierarchy Parent vs. Additional Parents

Primary Hierarchy Parent:

• Used for tree structure in List tab
• Determines indentation level
• Typically derives_from relationship
• Defines custom ID prefix

Additional Parents:

• Shown in Details tab only
• Various relationship types (implements, verifies, traces_to, etc.)
• Provide traceability, don't affect tree structure
• Used in traceability reports (coming soon)

Moving Requirements (Remap)

To change a requirement's position in the hierarchy, use the Remap dialog.

Using the Remap Dialog

1. Open the requirement you want to move
2. Click Remap (or the equivalent action in the dropdown menu)
3. Select the new parent:
   • Root: Move to top level (no parent)
   • Existing Requirement: Move under that requirement
4. Confirm

The dialog shows a preview before applying so you can verify the impact.

Subtree Moves — One Click Moves Everything

When you remap a requirement, all of its descendants move with it automatically. You don't have to remap each child separately.

Example: you imported a Word document and got this subtree under CR017:

CR017                            ← doc-root from Smart Import
├── CR017.1
│   ├── CR017.1.1
│   └── CR017.1.2
└── CR017.2                      ← you want to move this whole branch
    ├── CR017.2.1
    │   ├── CR017.2.1.1
    │   └── CR017.2.1.2
    ├── CR017.2.2
    ├── CR017.2.3
    │   └── CR017.2.3.1
    └── CR017.2.4
        └── CR017.2.4.1

Remap CR017.2 under CR012.SYS005 (which already has children SUB001 and SUB002). The result:

CR012.SYS005
├── CR012.SYS005.SUB001          (existing, unchanged)
├── CR012.SYS005.SUB002          (existing, unchanged)
└── CR012.SYS005.SUB003          ← was CR017.2
    ├── CR012.SYS005.SUB003.FUN001  ← was CR017.2.1
    │   ├── CR012.SYS005.SUB003.FUN001.SFUN001  ← was CR017.2.1.1
    │   └── CR012.SYS005.SUB003.FUN001.SFUN002  ← was CR017.2.1.2
    ├── CR012.SYS005.SUB003.FUN002  ← was CR017.2.2
    ├── CR012.SYS005.SUB003.FUN003  ← was CR017.2.3
    │   └── CR012.SYS005.SUB003.FUN003.SFUN001  ← was CR017.2.3.1
    └── CR012.SYS005.SUB003.FUN004  ← was CR017.2.4
        └── CR012.SYS005.SUB003.FUN004.SFUN001  ← was CR017.2.4.1

Eight requirements moved in a single operation. The SUB003 slot was the next available sibling under CR012.SYS005 (after existing SUB001 and SUB002).

What Happens Behind the Scenes

Custom IDs regenerate in canonical project format. Bare-number suffixes from Smart Import (CR017.2.1.1) are converted to the project's abbreviation format (CR012.SYS005.SUB003.FUN001.SFUN001) on move.

Descendants update recursively:

• Every child, grandchild, great-grandchild's custom_id is recomputed
• Counter values reset under the new parent (start at 1 within each level)
• Type-specific abbreviations come from your hierarchy taxonomy

Traceability preserved:

• Simple-FMEA linked_requirement_id fields auto-update to the new custom_ids
• Parent relationship records (internal database IDs) remain intact
• Version history continues unbroken

Safety guards:

• Circular moves blocked (you can't move a requirement inside one of its own descendants)
• Same-project enforced (you can't remap across projects — use Branch from Baseline if you need that)
• Hierarchy-level on the moved root auto-adjusts to be one level deeper than the new parent's level

External References

Remap changes custom_ids. References in external documents (Word, Excel, emails) point to the old IDs and will not auto-update. Plan remaps before external publication.

Use Case: Reorganizing After Smart Import

Smart Import deposits an entire Word document under one doc-root. The intended workflow is:

1. Run Smart Import, get a doc-root CR017 with everything inside
2. Inspect the imported structure
3. Use Remap to move individual subtrees (e.g. CR017.2) into their correct place in your project (e.g. under an existing System Requirement)
4. Delete the doc-root once all useful subtrees have been relocated, or keep it as a record of "what came from spec_v3.docx"

Version History

Every edit creates a version history entry showing what changed.

Viewing History

Location: Details tab → Version History section (bottom)

What's Shown:

• Version Number (v1, v2, v3, ...)
• Timestamp (when changed)
• User (who made the change)
• Fields Changed (what was modified)
• Change Notes (if provided)

Example:

Version History
┌────────────────────────────────────────────┐
│ v3 - 2024-01-15 14:23 by John Smith       │
│ Changed: text, status                      │
│ Notes: Updated power spec per customer     │
├────────────────────────────────────────────┤
│ v2 - 2024-01-10 09:15 by Jane Doe         │
│ Changed: priority                          │
│ Notes: Elevated to high priority          │
├────────────────────────────────────────────┤
│ v1 - 2024-01-05 16:45 by John Smith       │
│ Notes: Initial requirement created         │
└────────────────────────────────────────────┘

Comparing Versions (Coming Soon)

Future capability:

• Click version number to view that version's content
• Select two versions to see side-by-side diff
• Restore previous version (undo changes)

Best Practices

When to Use Inline Editing

✅ Use Inline Editing For:

• Quick status updates
• Adding JIRA link
• Updating change notes
• Minor text corrections
• Single field changes

❌ Don't Use Inline Editing For:

• Changing parent AND type together
• Major text rewrites (use modal for larger text area)
• Adding description (not available inline)

When to Use Full Edit Modal

✅ Use Modal For:

• Multiple field changes
• Moving requirement to new parent
• Adding or editing description
• Changing owner assignment
• Complex edits requiring validation check

Writing Good Change Notes

Good Examples:

✅ "Increased power requirement from 250 HP to 300 HP based on
   customer email dated 2024-01-10 (ref: email-thread-xyz)"

✅ "Changed from Draft to Approved after design review meeting.
   Reviewed by: John, Jane, Bob. Meeting notes: DOC-456"

✅ "Added JIRA link PROJ-1234 to track implementation progress"

✅ "Moved from System Requirements to Subsystem per architecture
   refactoring decision (see ADR-007)"

Bad Examples:

❌ "Updated" (what was updated?)
❌ "Fixed typo" (which typo? what was the impact?)
❌ "Changed stuff" (be specific)
❌ "" (blank - no context for future readers)

Editing Tips

1. Save Frequently - Inline edits save immediately, use them often
2. Provide Context - Always fill change notes for significant edits
3. Verify Children - Check child requirements after moving parents
4. Review History - Use version history to understand changes over time
5. Test Parent Changes - Preview impact before moving requirements

Validation Rules

Field Requirements

Field	Required?	Validation
Title (Text)	✅ Yes	Cannot be empty
Type	✅ Yes	Must be valid hierarchy type
Status	Optional	Must be from predefined list
Priority	Optional	Must be High/Medium/Low
Owner	Optional	Must be organization user
JIRA Link	Optional	Free-form text
Description	Optional	Free-form text
Change Notes	Optional	Free-form text

Hierarchy Enforcement

The system prevents:

❌ Invalid Parent-Child Combinations

• Can't make a Subsystem parent of a System
• Can't skip hierarchy levels inappropriately
• Type compatibility enforced by dropdown

❌ Circular References

• Can't make a requirement its own ancestor
• Parent chain must be acyclic
• Validation occurs on save

✅ Allowed Operations

• Any requirement can become root (no parent)
• Proper hierarchy level transitions
• Multiple children of same type under one parent

Type Change Restrictions

When changing a requirement's type:

Allowed if:

• ✅ New type is compatible with current parent
• ✅ New type is compatible with existing children
• ✅ Hierarchy rules permit the transition

Blocked if:

• ❌ Would create invalid parent-child relationship
• ❌ Would violate hierarchy configuration
• ❌ Would create circular reference

System Behavior: Dropdown only shows valid types for current context

Keyboard Shortcuts (Coming Soon)

Planned shortcuts for faster editing:

• E - Edit selected requirement (inline mode)
• Shift+E - Edit in modal (full form)
• Ctrl+S - Save inline edit
• Esc - Cancel inline edit
• Tab - Next editable field
• Shift+Tab - Previous editable field

Troubleshooting

Inline Edit Button Not Appearing

Possible Causes:

1. No Requirement Selected - Click requirement in tree first
2. Wrong Tab - Make sure you're on Details tab, not AI Analysis
3. Read-Only Permission - Check if you have edit rights
4. Field Not Editable - Some fields (custom_id) are auto-generated

Solution: Verify you're on Details tab with a requirement selected

Changes Not Saving

Possible Causes:

1. Validation Error - Required field left empty
2. Network Issue - Check internet connection
3. Session Expired - Re-login if timeout occurred
4. Permission Issue - Verify edit permissions

Solution: Check error message, verify all required fields filled

Custom ID Not Updating After Move

Expected Behavior: Custom IDs update after moving parent

If Not Updating:

1. Refresh page (F5)
2. Check if move actually saved (look for error toast)
3. Verify parent change was allowed (hierarchy rules)

Prevention: Wait for success toast before navigating away

Lost Edits

Inline Editing:

• Changes save immediately when you click ✓ Save
• No auto-save - must click Save or changes are lost

Modal Editing:

• Changes only save when you click "Save" button
• Clicking outside modal cancels (no save)
• Navigating away loses unsaved changes

Prevention: Always click Save button before closing

What's Next?

• Parent Relationships - Many-to-many traceability
• Hierarchy Management - Navigate tree structure
• AI Analysis - Use AI to improve requirements
• Version Control - Track requirement changes over time